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
Mar 162012

The last week or so, I’ve been working on sample code for the Source Editor API. While this API is not incredibly mission critical, in that it doesn’t directly affect web developers, and isn’t in the critical path for documentation, I’ve enjoyed this work, and the time spent writing about it — and, more importantly, building sample code for it — has been educational.

One thing that occurred to me is this: we need more real-world examples of how to do things. Too many of our examples are simple, fictionalized snippets of code that don’t show you how to do things in the greater scheme of getting things done. However, you still need to document things in context, too.

What I propose is this: what if we set up a section on MDN for larger examples of all kinds, where each page is a complete example, with downloadable code and one section for each method or interesting section of the example, talking about how it works? Then we can link to those sections from the relevant documentation site-wide.

For instance, this example I’m working on shows how to do all of the following things:

  • Create a new XUL window
  • Import several JavaScript code modules
  • Add a Source Editor to the window
  • Interact with the Source Editor
  • Create and manage a menu bar
  • Check and uncheck menu items given the state of the source editor
  • Update the display in a status area of the window given information obtained from the source editor
  • Asynchronously fetch the contents of a page using NetUtil
  • Overlay XUL from within the browser into the source editor to re-use UI and code
  • Save the text from the source editor to a local file on disk
  • Display alerts using the prompt service
  • Call various methods from XUL definitions of UI
  • Add and remove event listeners
  • Some parsing of file and pathnames
  • Set the title of a window based on the name of the item being edited
  • Add an item to the browser’s content area context menu under specific conditions

That’s a lot of stuff, and being able to demonstrate how all of those things are done in a real-world extension has a lot of value. By having a page that covers all of the things this add-on does, then being able to link to the appropriate parts of that page from all over the site, we can really bring our documentation to a whole new level.

Any thoughts?

 Posted by at 7:30 AM