Jan 182012

During the Engagement team work week last week, the four on-staff Mozilla developer documentation writers (myself, Janet Swisher, Jean-Yves Perrier, and Will Bamberg) had a sit-down to talk. This was a big deal since it was Jean-Yves’s first time meeting with us in person since joining Mozilla on December 1, and Will’s first time meeting with us since he’s been largely off doing fairly separate stuff documenting the Jetpack SDK.

We had a long discussion about a wide variety of things, and I figured I’d blog about it, to share those ideas and thoughts with the wider Mozilla community — and to flesh out the ideas from the outline format I took the notes in.

One area we spent a lot of time talking was about automation and how little of it we currently do when creating documentation.

One-way generation of documentation

Right now, there’s a Firefox extension by Trevor Hobson that we can use to do one-time generation of reference documentation from IDL. This has been a great tool for us but isn’t an ideal solution for a couple of reasons:

  1. It uses MXR to get the code and tries to use that to differentiate between releases. This used to work great but no longer does since we don’t create a new branch for every release anymore.
  2. It only works for IDL; it can’t parse C header files or JavaScript code modules.
  3. It only works once. Once the article is generated, all future revisions must be done by hand, unless you’re willing to lose any edits you’ve made to the article in the interim.
  4. It only works one-way. Once you’ve made changes to the article, you can’t get those back into the IDL.

Two-way documentation sync: A dream within a dream

Our dream — and it may be an impossible one, or at least extremely unlikely — is the notion of being able to do two-way synchronization of reference documentation back and forth between the wiki and the source. This would obviously involve a lot of code to manage, and getting resources to create something like this is unlikely anytime soon.

The idea is that you could pull content into the wiki from comments in headers and the like, and then use the wiki to edit that content, publishing patches back to be pushed to the tree in an automated fashion after some sort of review. Likewise, periodically, the documentation would be refreshed based on changes made to the headers.

The details would have to be worked out, obviously, but this is a fascinating idea that, if it could be perfected, could make our reference documentation not only easier to maintain, but would help the writers make sure the comments in the headers were kept accurate and tidy.

Automation and localization: A conundrum

Obviously, in-source documentation is inherently unfriendly toward localization. You don’t want to clutter up the code with multiple translations of the content, so localized content would have to be maintained separately. Automated content would only be in English; all localizations would likely, unfortunately, need to be done manually. However, we might be able to mitigate that somewhat. If the editing of automated docs were more structured than the current free-flow system we have (that is, if each method, for instance, were edited as individual components rather than as part of a whole, for example), it would be relatively easy to pull in just the changed stuff and know exactly what needs translating, quite easily.

It’s been suggested that, at least for younger folks outside the English-speaking parts of the world, reference documentation being only (or primarily) in English isn’t an issue since they learn it in school anyway. However, older users may have little if any English. Either way, having translated material is usually preferable, at least to some folks, as long as it’s accurate and current.

Talk about planning ahead!

There are a lot of things to think about when automation is involved, and we’ll be talking about this more in the future. Given that a lot of this is extremely far-forward looking, there’s no rush here! Let’s think about it and get it right.

 Posted by at 9:00 AM

This site uses Akismet to reduce spam. Learn how your comment data is processed.