Documentation Update

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:

• tested, rewrote, reformatted, consolidated, and provided basic and advanced tested examples for 76 docs pages over the course of the last month when this project began. Highlights:
  • mt:Entries
  • Category-related tags
  • Archive File Path Specifiers
  • mt:Var
• produced a documentation style guide
• written a plugin to provide the ability to link to headings within the docs (HeadingLinks plugin)
• updated various movabletype.org templates and styles to provide more context and links to define relationships between various features.
• created various utility templates to list most recently updated docs, docs with little or no content, and docs which need review from some Perl experts, etc.
• added a way for admins to note when a comment’s content has been incorporated into the main doc.

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):

• @need_review - Potentially complete, but should be reviewed by a Perl expert.
• @need_backend_help - Need help authoring from a Perl expert.

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.