Not a developer? Go to MovableType.com

News

Documentation Update

By Beau Smith
Posted July 20, 2009, in News.

This week we’ll be previewing some of the new features of Movable Type 4.3 (try the Movable Type 4.3 beta). I’ll start the week off with a post on the my progress updating and improving the Movable Type documentation and Matt Jacobs, MT product manager, will be posting about other features of MT 4.3 later in the week.

Intro

In product documentation, the manual is the product. If a feature isn’t defined, it doesn’t exist as far as the user can tell. If a feature is described badly, the user will perceive the product to be a bad product. Thus, do not skimp on the documentation. Randal L. Schwartz, Perl author

Documentation should be an integral part of the development of a new feature. It should start as a Specifications document, then be used for Quality Assurance testing of the feature, and then published publicly as the Official Documentation for the feature.

Describing how a feature works provides new insight into how it could be coded better, reveals bugs, or gives inspiration to new features.

Documentation is even important to the developers who wrote it as sometimes they have totally forgotten their strategy at the time, or perhaps their experience since writing the code has provided them new insights.

Good documentation will reduce the amount of questions that are asked of our developers and provide them with more time code in peace.

MT Docs History

One of the biggest complaints we hear from Movable Type users is lack of documentation. Those who have looked under the hood know that it’s powerful, but for the majority of users documentation is where they turn when they want to find answers.

In the past, valiant efforts have been made to improve the docs, but they’ve always been halted by higher priority tasks or due to the loss of resources. Many of docs have suffered from lack of completeness or worse inaccuracy. With no official documentation guidelines or style guide to follow and documentation often being the least fun part of programming, the docs were often limited to very limited description of functionality.

Since MT4 was released, whenever possible, I’ve taken the time to add clarity and/or examples to the docs during and between various projects… and I even wrote up a POD Doc formatting guide for internal use.

We’ve always stressed the production of documentation, but true progress in bringing this work public has been hindered due to the complication of formatting docs in POD, requiring them to be checked into in the Movable Type code and then later synced to movabletype.org. Since docs were often updated directly on movabletype.org and not in the code, keeping these two separate locations manually synced was not a scalable nor desirable solution.

Movable Type 4.3 Release

So with the docs being a part-time pet project, I was happy to see that “documentation” was a feature listed for the MT 4.3 release. When I was asked me to take on the docs as my ongoing project, I was stoked!

Upon initial survey, I found that the docs was composed of 1452 total pages. Sheesh… where to begin?

Knowing that this wouldn’t be my only project and that there was a chance my priorities could change, I figured that it was important to establish a framework and style guide such that when developers have time, they can follow this guide to quickly create complete, accurate, and consistent documentation, formatted to fit in seamlessly with the rest of the documentation… thus providing a continued increase in quality over time.

Knowing that some of the 1452 pages would take 10 minutes, others would take a few days, and that I would find there were features for which docs didn’t exist, I figured I would start updating the docs with reported bugs, docs with little or no content, and those which were most visited based upon Google Analytics results.

Starting with the the 812 pages of docs for tags, modifiers, config directives, and appendices would give me a good sense of what a style guide should look like and would provide valuable insight when shifting focus to the 640 pages of guides, release notes, etc.

Current Status

So far I have:

Future Plan

Once docs related to Movable Type Markup Language (template tags, tag modifiers, config directives) and other appendices are more complete overall, work will shift to developing guides to assist in the use and learning of Movable Type’s features. While writing guides, related docs will be updated as necessary to support the guides.

Currently many of the guides are grouped by user type, but there is a desire to convert the structure to a more topic-based set of guides. (This way to learn about using “assets”, it won’t first require guessing if the desired information would be categorized under Author, Designer, Administrator, or Developer docs… rather you’d find a guide called “Using Assets” which would contain everything related to assets.)

An outline of how the guides section will be architected hasn’t been defined, but some have been suggested.

You Can Help!

  1. Create/update a page using the style guide to help keep the docs consistent and complete.
  2. Submit the docs via any of the following methods:
    • Submit a case in bugs.movabletype.org. Just a Title and description are necessary, the link is pre-configured to place the case in the Docs area for triage.
    • Leave a comment on the page of the doc with the notes
    • Edit the docs directly if you’re a community member who has been granted access to the docs install. (Leave a comment—as a native MT user—on this post if you’d like to apply for an account.)

Feel free to start anywhere in the docs. I’ve created outlines in the style guide for documenting tags, modifiers, and config directives.

Because I’m not a Perl expert (yet!) there are some docs which I’ve edited, but was unable to complete. I have tagged them with a private tag and created a couple index templates to list them. Most of the pages are stubbed out with questions placed in html comments. (Once docs are updated, the respective private tag should be removed):

If you have any questions or feedback, please feel free to email me: Beau at Six Apart


Some thanks… to Su, Elise, Jesse Jay, and Byrne and other community members for proofing, testing, providing feedback, submitting documentation bugs, and tweeting about the updates and activity; Matt Jacobs for some templating suggestions; to Brad Choate and Mark Paschal for providing insight into the Perl logic and guidance in creating the HeadingLinks plugin; and thanks to David Jacobs for making time for this project.

Back

10 Comments

Dan Dickinson

Dan Dickinson on July 21, 2009, 7:22 a.m. Reply

It’s absolutely great to hear that the documentation is getting such a close look. It’s a constant go-to reference for our site implementations, and the changes have already made our lives easier.

That said, I’d like to apply for doc editing access - just so I can help contribute back!

Matt Jacobs

Matt Jacobs on July 21, 2009, 9:23 a.m. Reply

Just wanted to give Beau a public shout-out. The work you did is fantastic!

Florent - SAV

Florent - SAV on July 22, 2009, 8:22 a.m. Reply

Thank you so much !

Bill

Bill on July 22, 2009, 10:15 p.m. Reply

Thanks for working on this Beau. Your work on the mt:Entries has helped me out already.

Jun Kaneko

Jun Kaneko on July 22, 2009, 10:40 p.m. Reply

This is great. I’m looking forward to collaborate with English / Japanese documentation more than ever !

Sparticus

Sparticus on July 23, 2009, 1:18 a.m. Reply

Brilliant, the amount of times I’ve tried to do something I know is possible, but can’t find the documentation for is, well, probably only a few. But still frustrating. Thanks for doing this.

gulliver

gulliver on July 29, 2009, 9:24 p.m. Reply

Considering how much VC funding SA has had, it’s bloody ridiculous that it’s been so bad for so long.

And, considering the huge amount of user-contributed stuff that’s been available through the forums for years (including a whole lot of ‘how to make MT do useful stuff that SA don’t bother to tell you about), it’s even dafter.

indigirl

indigirl on July 30, 2009, 8:58 a.m. Reply

I’d love access to directly work on docs. I’ve been heavily developing MT plugins fulltime and would like to contribute what I’ve learned.

Francisco Aguirre

Francisco Aguirre on July 30, 2009, 10:51 p.m. Reply

There are times when I need to do something, but I can’t find it in the documentation, so I would look forward to see an improved docs search in the website.

Also, as in MT 3.x, I would love to have a complete PDF version I could download & print, so that I don’t have to visit the site every time I have a question…

Keep up the good work ;)

Lorrie

Lorrie on July 17, 2012, 10:31 a.m. Reply

Well done Beau! To do entire work on more than 70 doc pages is really hard work.