Mar 292012

Firefox is changing fast. So is the Web, for that matter. There are so many new APIs and technologies pouring forth from the clever minds of all those engineers that the developer documentation team is struggling to keep up. Indeed, we’re slowly falling farther behind.

That means we need to sort out which documentation issues need addressing the most urgently.

What documentation is “important”?

There are basically two categories of high-priority documentation:

  1. Very new and exciting technologies that we want to be able to make a big deal of. These need documentation so that developers can jump into them quickly and easily.
  2. Significant changes to existing technologies that may cause problems for existing web content or Firefox add-ons.

The documentation team isn’t always the best set of people to determine which documentation issues fit into these categories. As such, we need to start recruiting others to participate in the prioritization process.

Who can help?

Those two categories of high-priority documentation I mentioned above just happen to correspond to two very different sets of people:

  1. Evangelists and product marketing folks are ideal for flagging the priority on documentation issues that correspond to new and exciting technologies. They want to be able to promote technologies through blog posts, press releases, release notes, and so forth, and as such want to have documentation for those high-visibility technologies. Preferably before they start making a fuss about them.
  2. Engineers and developers tend to know which changes are going to be a headache for web and add-on developers. That puts them in a perfect position to mark the priority on these documentation issues.

How do you help?

If you fit into one of these categories (or, really, even think you’d like to try to help out), you can easily help prioritize our documentation issues! We use a documentation tracker web application developed by Florian Scholz. It interfaces with Bugzilla, using the dev-doc-needed and dev-doc-complete keywords we apply to bugs that affect documentation, but adds additional features, including support for tracking bugs by Firefox release, additional note fields, and, most importantly for the purposes of this blog post, a priority field for each bug.

So here’s how you can help: go to the documentation tracker, log in (using your Bugzilla login), and peruse the list of bugs. Click the edit button at the right edge of the row for any bug you can help prioritize, and set the priority. It’s that easy; it’s a wonderful tool and we use it a lot.

What do the priorities mean?

The priority field can be set from 1 to 5. Each of these values means something fairly specific (in fact, I’m hoping Florian will update the tool to include a reminder of the meanings in each menu item in the popup for the priority). Those values are as follows:

  1. Must be documented if possible within one week after reaching Aurora.
  2. Must be documented if possible within one week after reaching Beta.
  3. Must be documented if possible within one week after release.
  4. Must be documented if possible before the next release.
  5. Should be documented. Someday.

Yes, these values are tied to Firefox releases. However, that gives a general sense of the urgency of the item, even independently of Firefox itself.

Let’s say you’re an evangelist, and you’re looking over the list and see that a particular bug corresponds to a technology you want to blog about when the corresponding release reaches Beta. You should in that case set that bug’s priority to 2. That lets us know to put a rush on that item, but not to block any priority 1 items on it.

It’s not a guarantee!

It’s important to keep in mind that our resources are stretched pretty thin right now. We can’t guarantee that items will be documented by the time the priority requests it be done. We will, however, do our best. And, of course, you should always feel free to contribute documentation. Even a rough outline will encourage someone to come along and spruce things up!

Help us help you

The developer documentation team is here to help. We can get things done faster if you give us all the information you can about when you need something written and, if possible, how it works (or at least the name of someone we can contact to ask questions). Feel free to add that to the notes field in the doc tracker!

And, as always, feel free to contact me by email or drop into the #devmo channel on IRC with your developer documentation related questions.

 Posted by at 9:31 AM