Mar 102008

We have several ways to get documentation issues taken care of on the Mozilla project.  You can tag an existing bug with the “dev-doc-needed” keyword to let the writers know that there’s something in that bug that will require a documentation change.

You can also file a bug against the Mozilla Developer Center product.

These are great ways to get major issues queued up to have someone take a look at them, and I strongly encourage people to use them.

But try to consider this when filing a bug, or tagging it for documentation needed: How long would it take you to edit the documentation yourself?  Often, the documentation bugs come down to just a few minor edits.  Maybe adding a note saying that a feature was deprecated in Firefox version X, or a note that a particular behavior changed.  It would take the engineer that made the change less time to edit our wiki to reflect the change than it does to file a bug on it.

This is especially important when you consider this: the writers don’t necessarily know the ins and outs of the code you’re working on.  All too often, I settle in to research a documentation bug and spend many hours reading the bug, reviewing the code, and so forth, only to discover that it comes down to a one or two line change to the documentation.

Probably 80% of the bugs marked as “dev-doc-needed” are like this.  I spend an average of two hours on each of these, and most of them are extremely minor edits to the documentation when you get down to it.

Worried about your writing?  Don’t!  We have wiki gnomes that clean up things like that, and it’s a lot faster to tidy up a hurriedly-written documentation update than to do it from scratch!

If you’re totally wiki-phobic, at least add a comment to the bug that specifically lays out what the issue is that needs to be addressed.  Most of the “dev-doc-needed” bugs don’t have anything in them that says what actually requires a documentation edit, which winds up requiring me to read sometimes dozens of comments that are often cryptic, then ask a lot of annoying questions, only to again find out that the edit needed is very small.

So when you submit a bug against docs or mark a bug as “dev-doc-needed” — please take a moment to think: can I fix this myself?  If not, please add a comment to the bug laying out specifically what needs to be documented.  That will help keep me from going completely insane, and we all know what kind of documentation gets written by insane people.

 Posted by at 3:32 PM