As you work on Mozilla, you’ll often file bugs or submit patches that will involve changes needing to be made to the documentation on MDN. I’ve written an article on MDN about this issue, and I’m duplicating it here to get it in front of more people that need this information.
Flag your bugs
When you file a bug that, upon resolution, will likely require that documentation be updated, you should add the dev-doc-needed keyword to the bug:
You don’t need to wait until the bug is fixed. Indeed, it’s easiest for the doc team if you add this keyword well in advance of the bug being resolved. That lets us plan ahead. That said, it’s never too late to apply dev-doc-needed to your bugs!
Also, note that if you use the addon-compat keyword to flag that a bug will impact add-on compatibility, you should absolutely also add dev-doc-needed!
The writing team uses Bugzilla queries, as well as a special documentation tracking site that interfaces with Bugzilla, to track our work. By using dev-doc-needed, your bugs will get brought to our attention at the right time to ensure the best odds that your stuff will be written up in a timely manner.
When the bug’s contents are documented, the person that did the work will replace the dev-doc-needed keyword with dev-doc-complete and, ideally, add a comment to the bug with links to the pages that were updated or created to cover the bug’s contents. You should try to review the changes to ensure that the writer got things right.
Indeed, if you love Mozilla, you’ll be sure you’re available to help out if the writer has questions. They may contact you by email, or post questions as comments on the bug. Try to take a few moments out of your busy day to answer questions.
Provide information to the writers
That brings us to the next point. Not only should you be sure to answer questions the writers bring to you, but a little simple preparation can stave off a lot of back and forth. Try to add a note to the bug that indicates exactly what needs documenting. A lot of bugs have pretty cryptic descriptions, or the actual documentation issue at hand isn’t obvious from the bug’s description.
For example, a bug might have a summary like “foobar.com doesn’t work in Firefox 45”. There may then be pages and pages of comments where the problem is debated, possible solutions suggested, and so forth, followed by the bug eventually being marked as resolved. With no other information, the hapless writer is left to pore over all those comments and the patches, hoping to figure out what needs documenting.
When the patch is finally checked in, you should try to add a comment that summarizes what the final resolution was. This can be either “Writers: check out comment 32” if there’s already a comment that explains the final resolution, or a quick summary of what’s changed, like “Check out the new method and attributes in nsISomeInterface” or “We added the someStandardDOMMethod” method to DOM elements”. Doing this can save the writers a lot of time (time that could better be spent writing even more stuff), and can save you from having to answer pesky questions.
It’s also helpful, of course, if your bug includes a link to the specification or design document for the feature being affected by the patch.
Just having directions on where in the code to look, or what subtle change has occurred, can make all the difference between your change being documented quickly and having it languish for a long time because it scares the writers off.
What if there’s not a bug for it?
Sometimes, you notice something’s wrong with the documentation. Maybe there’s a missing article, or you realize we need a guide on how to use some technology, and there doesn’t seem to be one. You can, of course, write it yourself. But if that doesn’t work for you, feel free to file a bug against the Documentation Requests product on the Mozilla Developer Network component on Bugzilla.
Feel free to update the documentation yourself
MDN is a wiki! You can log in and update the documentation yourself. A lot of programmers don’t consider themselves up to the task of writing documentation, or are crazy busy, and that’s okay! That’s why we have writers, and that’s why we have all the above tips.
However, if you have a few minutes, and feel comfortable doing it, feel free to log in and apply the necessary fixes yourself. This is often really simple for minor changes to the behavior of something, and can possibly save everyone time and effort.
For that matter, if you have the time to jot down relatively thorough notes about your change, you can toss them into the bug, or add them to the wiki. Our happy, helpful documentation gnomes live to clean up your writing, so don’t be afraid to try.
Ask for help!
If you’re not sure how to get something handled in documentation, or are trying to update the docs and are stuck, feel free to pop into #devmo on IRC, where the doc team hangs out, or ask questions on the documentation newsgroup.
