Developer documentation process

In order to improve the quality of our documentation, and our ability to coordinate among the various members of the Mozilla documentation community, we have a process by which documentation is maintained. This article describes how this works and offers useful links to help you ensure that the work you do is as helpful and useful as possible to the community of Web and Mozilla developers.

Getting documentation written

If you're browsing MDN and see a mistake, or a spot where documentation or code sample needs to be added -- or you're a developer and have made a change that should be documented -- you should take steps to help ensure the problem gets fixed. There are a few options here:

1. Fix it yourself. It's a wiki, so just click the big blue Edit button at the top of the page and make the required changes. If new documentation needs to be written, you can absolutely do that too. Don't be afraid! We have writers and volunteers that specialize in tidying up your writing and layout if you make mistakes. See Getting started for our guide to contributing to MDN.
2. If there's a development bug related to the topic at hand -- say for a new API you've added -- you can add the keyword "dev-doc-needed" to the development bug. This will let the writing team know that a documentation bug needs to be filed. However, it would be preferable if you'd skip this step and instead...
3. File a documentation request bug. We have a very handy, easy-to-use form for quickly filing documentation requests.

The official home for all documentation-related issues is the Developer Documentation component in Bugzilla. If your request isn't there, it's very likely not going to get written about!

Where documentation bugs come from

When a developer and a product love each other very much...

Seriously, though, there are a number of places from which documentation bugs can originate:

• Someone reading the documentation spots an issue such as missing or incorrect content and files a bug.
• Someone emails one of the writers asking that something be written or revised, and the writer, in turn, files a bug.
• During a discussion on IRC, an issue with the documentation is revealed, and a writer or developer files a bug.
• Someone flags a development bug with the "dev-doc-needed" keyword, and someone follows up by filing a documentation bug; they then change the keyword on the development bug from "dev-doc-needed" to "doc-bug-filed".

Filling out the documentation request form

The documentation request form significantly simplifies the process of requesting developer documentation additions or changes. It guides you to the proper filling-out of fields, removes fields that we don't use, and automatically sets values for other fields based on user inputs.

Request Type

This required field must be set to either "New Documentation" or "Correction." This helps us identify the scope of work involved with your request, to some extent, and will also help us keep in mind whether or not we should be looking for existing pages to revise.

Topic

This lets you indicate the general topic area of the documentation you're requesting. Options include things like "HTML", "Firefox OS", and "JavaScript".

Summary

This is a one-line summary of what documentation changes you're requesting. You don't need to go into tons of detail here. That's what the Details section below is for.

Technical Contact

The email address of someone who can be contacted by the writing team if help is needed as we gather information in order to write the material requested. We may also contact this person for a technical review after the writing is completed. This field supports lookups from the Bugzilla user database to help you get the email addresses correct.

Gecko Version

The version of Gecko corresponding to the requested material. For example, if feature "Wonderbar" was implemented in Gecko 32, you'd specify that here.

Details

A text area in which you can describe the requested documentation in more detail. You should feel free to include more information about potential contacts for help, what types of material you think are needed, and, ideally, notes we can use as we compose the documentation (such as links to specifications or design documents).

Development Bug

The Bugzilla bug number of a development bug on which this documentation relies. By setting this optional field, you establish a relationship between the two bugs that can be used to help track progress and look up information, since often development bugs' comments and attached patches include extremely useful information.

Urgency

This field lets you specify how urgent you think the requested documentation is. By default, this is "No Rush", meaning that you're fine with us getting to it when we have time. You can also specify that it needs to be done immediately, or that you'd like us to try to finish the documentation before the specified Gecko version reaches a particular stage of release preparation.

What happens next

Once a documentation request is filed and prioritized, someone will eventually come along and document it. We'll try to do them in order of priority, but there are other factors at play, including availability of people with the needed backgrounds and skills. Just because you've given a documentation bug a high priority level doesn't mean it will automatically be written about ahead of anything else out there. But we will try.

Triage

Every other week, during the MDN community meeting we hold in the #devmo channel on IRC. This happens on alternate Wednesdays, at 10 AM Pacific Time. At the end of these meetings, we review bugs that have the "dev-doc-needed" keyword on them and determine which ones need bugs filed under Developer Documentation. After the meeting, those bugs get filed and the development bugs get "dev-doc-needed" removed and "doc-bug-filed" added.

Alternatively, if the issue is easy to fix, we will leave it flagged "dev-doc-needed" for up to two weeks; if someone fixes it during that time, "dev-doc-needed" is changed directly to "dev-doc-complete". Otherwise, during the next triage we go ahead and file the documentation bug and set "doc-bug-filed".

Writing

The writing team (which consists of four staff writers and an enthusiastic community of part-time volunteer writers) will select writing tasks from the pool of Developer Documentation bugs that have not yet been resolved. Only items in that list are likely to be considered for writer time, and the better composed the request, the sooner you're likely to see writing take place.