Sep 052012
 

If you hadn’t noticed, the pace of development at Mozilla has really picked up lately. Between the ongoing rapid progress on the Boot to Gecko project, the six-week development cycle of Firefox, the web apps, marketplace, and Persona projects, not to mention other projects, it’s become clear that we need to start being more careful about our documentation workflow.

For that reason, we’re going to make some changes to our documentation process.

What’s changing?

In the past, too many person-hours of writing work have been used documenting technologies that were so far from fully-baked that we’ve had to redo (sometimes more than once) these documents. Often, the docs never get properly updated (I’m looking at you, IndexedDB). This is a huge waste of time in an era in which our excellent developers are pumping out so much new code and so many new APIs at a faster pace than ever.

Instead, we will only document new APIs when we can be given a reasonable degree of assurance that they’re stable.

  • For an API that is expected to be standardized, it has, at a minimum, been submitted to the appropriate standards body and gotten through at least one round of feedback and revisions. This will work out enough of the kinks that we can feel good about documenting it.
  • For an API that’s expected to be Mozilla-specific, it has settled down and the developers behind it are able to convince the docs team that it’s stabilized.

This likely means there will be times when the documentation team doesn’t feel that something is ready for documentation as soon as other groups would like to see the docs written. This is an unfortunate side effect of the remarkable productivity level of our development team! Someday, I hope our documentation team will be large enough to keep up with them. But until then, we’ll have to be more selective.

How you can help

If you’re a developer, the first, easiest thing you can do to help is to ensure that your code and headers are well commented, and that you use the dev-doc-needed keyword to mark any bugs that will require documentation updates.

A better, and in the end possibly even more helpful, thing you can do is to provide information! Send email (or, better, add notes to bugs) explaining what’s changed and what needs to be documented. Much of the time, dev-doc-needed means that we have to chase down the right people and ask a lot of questions that could have been avoided with the addition of notes to a bug.

You can go even further and actually update the docs yourself. This may not necessarily always be a viable course of action, but if you’re an expert on a topic, it may make more sense for you to spend a few minutes or an hour or two writing about it than to have the writing team have to do all the research of something you already know. It’s a better use of everyone’s time for you to write down a quick bit of information that we can clean up and turn into beautiful docs than for you and us to go around and around for ages until something’s finally written!

If you write a blog post about something that you think should be in the documentation, please either put it in the docs or at least let the docs team know about it!

The writing team hangs out in the #devmo channel on IRC. Feel free to drop in and ping us with your input or suggestions.

At this point, it’s all about making the best possible use of everyone’s time while turning out not just great code, but great documentation. Because what good is your awesome code if nobody can figure out what they can do with it, right?

 Posted by at 9:30 AM

  One Response to “Documentation processes in the busy world of Mozilla”

  1. “At this point, it’s all about making the best possible use of everyone’s time while turning out not just great code, but great documentation. Because what good is your awesome code if nobody can figure out what they can do with it, right?”
    => look at you, trying to (slightly) change Mozilla dev culture to encourage them to consider the doc as part of the product ;-)

    Needless to say I agree 100% to everything in your blogpost.