Getting documentation updated

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 those documentation updates occur.

Flag your bugs

When you file a bug which, upon resolution, will likely require its documentation being updated, you should add the dev-doc-needed keyword to the bug:


You don't need to wait until the bug is fixed. It's preferable, for the doc team, if you add this keyword well in advance of the bug being resolved. This lets us plan ahead. That said, it's never too late to apply dev-doc-needed to your bugs!

Note: If you use the addon-compat keyword to flag a bug will impact add-on compatibility, you should 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, improving the likelihood your efforts will be escalated in a timely manner.

When a bug's contents are documented, the person doing the work will replace the dev-doc-needed keyword with dev-doc-complete, adding 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 any changes to help ensure the writer is correct.

Many Mozillians choose to remain available, helping when writers have questions. You may be contacted by email, or they may post any questions as comments on the bug. It's especially helpful to set aside a few moments from your 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

This brings us to the next point. Not only should you make yourself avilable, to answer questions writers may have, some basic preparation can stave off a lot of back and forth.

Bug annotations and tags

Try to add a note to the bug, indicating exactly what needs documenting. A lot of bugs have rather cryptic descriptions, or the documentation issue at hand isn't obvious from the bug's description.

For example, a bug might have a summary like " doesn't work in Firefox 45". Then there may 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 patches, hoping to fathom what needs documenting.

When a patch is finally checked in, try to add a comment which summarizes what the final resolution was. Ideally, this should be a brief summary of what has 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 significant amount of time, which could better be spent writing even more, and might even save you from answering troublesome questions.

Also, if a comment on a bug contains information that should be documented, please add the comment tag "dev-doc-info" to this comment. That helps the docs team track down those tidbits of required information.

It's also helpful, if your bug includes a link to the specification or design document, for the feature being affected by the patch.

Having clear directions, navigating where in the code to look, or what subtle change has occurred, makes all the difference between your changes quickly documented, or scaring writers off and having it languish for a longer time.

Provide the writing team with links to sample code, or tests for the technology. Having easy access to this is a huge help. Helping the writing team know where the technology or API is implemented in the code, is a big help. Let us know precisely where to look for the code on mozilla-central, or github, so we too can locate it.

What if there's not a bug for it?

Sometimes, you notice something wrong with the current documentation. Maybe a missing article, or we need a guide on how to use a technology, and there doesn't seem to be one. You can, of course, write it yourself. If that is not possible, 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 so, log in and apply the necessary fixes yourself. This is often really simple for minor changes to the behavior of something, saving everyone time and effort, and more rapidly improves our documentation.

I can prove helpful if you jot down relatively thorough notes about your changes as you go. 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 to hand doing this can be a huge help, ensuring the documentation we produce is accurate, thorough, and truly useful.

Ask for help!

If you're not sure how to get something handled in documentation, or are trying to update the docs and feel stuck, pop over to #devmo on IRC. This is where the docs team hangs out, or alternatively ask questions on the documentation newsgroup.

See also

Here are some helpful links, with additional information you may find handy: