Feb 142014
 

Over the last few days, I’ve provided lots of information about what types of documentation MDN features, how to file a documentation request, and so forth. Now I’d like to share some tips about how to file a documentation request that’s clear and provides all the information the docs team needs in order to do the job promptly and well.

While adding the dev-doc-needed keyword to bugs is a great start (and please do at least that, if nothing else), the best way to ensure your documentation is produced in a timely manner is to file an actual documentation request.

Note: See also my older blog post about the documentation request form; that post is a tad out of date but may also be interesting/useful.

Ask early

The sooner you ask for documentation to be written, the better. Even if you haven’t started to actually write any code, it’s still not too early to file the documentation request! As I’ve mentioned in previous posts, the sooner we know that we may need to write something, the easier it is to nudge it onto our schedule when the time comes. This is both because of easier logistics and because we can ensure we’ve been following the status of your project and often can start research before it’s time to start writing.

As soon as you realize that documentation may need to be written—or updated—file a documentation request!

Write a useful summary

The bug summary should at a minimum mention what APIs or technologies are affected, and ideally will offer some insight into how out of date any existing content is or what Firefox release incorporates the changes. Some good examples:

  • Update FooBar API documentation for Firefox 29 changes
  • Document new interface nsISuperBar added in Gecko 33
  • Document that document.meh method deprecated in Gecko 30, removed in Gecko 31
  • Note in docs that WebSnickerdoodle support brought into line with WebKit implementation in Gecko 28
  • Docs for WebPudding say it’s unsupported in Blink but it is starting in Blink 42

Some bad examples:

  • Docs for WebGL suck
  • Update all docs for Gecko 42
  • Add documentation for <some word that doesn’t match the name of any spec/technology mentioned anywhere on the Web>

Be sure to use the right names of technologies. Don’t use your nickname for a technology; use the name used in the specification!

Where are existing docs?

If you know where the existing documentation for the material that needs updating is, include that information. Obviously, if you don’t know, we won’t make you hunt it down, but if you’re already looking at it and shaking your head going, “Boy, this is lame,” include the URL in your request!

This information goes in the “Page to Update” field on the doc request form.

Who knows the truth?

The next important bit of information to give us: the name and contact information for the person or people that can answer any questions the writing team has about the technology or API that needs documentation work. If we don’t have to hunt down the smartest person around, we save everyone time, and the end result is better across the board.

Put this information in the “Technical Contact” field on the doc request form. You may actually put as many people there as you wish, and this field does autocomplete just like the CC field in Bugzilla, using Bugzilla user information.

When does this change take effect?

If you know when the change will take effect (for Firefox/Gecko related changes, or for implementing open Web APIs in Firefox), include that information. Letting us know when it will land is a big help in terms of scheduling and in terms of knowing what to say in the compatibility table. This goes in the “Gecko Version” field in the doc request form; leave it “unspecified” if you don’t know the answer, or if it’s not relevant.

If you don’t provide these details, we’ll ask for it when the time comes, but if you already know the answer, please do provide as much of this as you can!

On a related note, providing links to the development bug which, upon closing, means the feature will be available in Firefox nightly builds is a huge help to us! Put this in the “Development Bug” field on the doc request form.

Be thorough!

Provide lots of details! There’s a lot of other information that can be useful, and the more you can tell us, the better. Some examples of details you can provide:

  • A brief explanation of what’s wrong (for problems with existing documentation), or what needs to be written.
  • A link to the specification and/or design documents or wikimo pages for the feature.
  • Relevant IRC channels in which the technology is discussed (for example, if it’s a gaming API, you might remind the potential writer to ask about it in #games).
  • Links to blog posts that the dev team(s) have written about the feature/technology/API. These are a great source of information for us!
  • Link(s) to the source code implementing the feature/technology/API.
  • Link(s) to any tests or example code the dev team has written. We use these to help understand how the API is used in practice, and often swipe code snippets for our on-wiki examples from these.
  • Target audience: does this technology/API impact open Web developers? App developers? Both? Only Gecko-internals developers? Add-on developers? Some other group we haven’t previously imagined? Green-skinned aliens? Tortoises?

Wrap-up

I hope this information is useful to help you produce better documentation requests. Not just that, but I hope it gives you added insights into the kinds of things we on the documentation team have to consider when scheduling, planning, and producing documentation and documentation updates.

The more information you give us, the faster we can turn around your request, and the less we’ll have to bug you (or anyone else) to get there.

We know Mozillians love good documentation: hopefully you can help us make more great documentation faster.

 Posted by at 4:26 PM