Getting documentation updated 编辑

As a contributor to Firefox, or other Mozilla projects, 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 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 that will impact add-on compatibility, you should also add dev-doc-needed!

The writing team uses Bugzilla queries 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's work 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.

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 help avoid a lot of needless back and forth communication.

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 "foobar.com 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 SomeInterface.webidl", or "We added the someStandardDOMMethod() method to interface SomeInterface". 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 describing 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.

Links to code

Provide the writing team with links to simple code examples 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?

You may 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 could of course fix the documentation yourself by updating the MDN content repo, but if you do't have time you should at least file an issue to tell us something is wrong.

Review the results

Once content has been written, often we'll ask for a technical review of it. 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, feel free to ask the writer's team for help.