As a contributor to Firefox, Firefox OS, or any Mozilla project, you'll often file bugs or submit patches that result in changes needing to be made to the documentation here on MDN. This article provides tips to help ensure that those documentation updates occur.
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.
Note: If you're working on docs and don't have access to edit the keywords field in Bugzilla, contact sheppy and he may be able to hook you up.
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.
Bug annotations and tags
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. Ideally, this should be a brief 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.
Also, if a comment on a bug contains information that should be documented, please add the comment tag "dev-doc-info" to that comment. That will help the docs team track down those tidbits of information.
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.
Links to code
Provide the writing team with links to sample code or tests for the technology; having easy access to this is a huge help. In addition, letting the writing team know where the technology or API is implemented in the code is a big help. Let us know where on mozilla-central or github to look for the code, so we can look through it.
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, please feel free to file a documentation request bug. See our extensive documentation for contributing to MDN for additional details.
Feel free to update the documentation yourself
This 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.
To update the documentation yourself, you'll need a GitHub account. Once you have that, you can log into MDN and edit any page on the site. See our Getting started with MDN guide for additional information.
Review the results
Once the content has been written, often we'll ask for a technical review. Having the right person on your team do that can be a huge help in ensuring that the documentation we've produced is accurate, thorough, and useful.
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.
See also
Here are some helpful links with additional information you may find handy.