Bit Stampede

A few months ago, we decided to set up a driver system for driving documentations on a release-by-release basis, with a writer taking lead on each release as it made its way through the release train process.

This… didn’t really work out. It was a noble experiment that failed.

We’re now in the process of switching to a per-topic documentation driver system. This will let us get documentation for the most important material done more quickly (at least in theory) regardless of when it ships. The driver for each topic area will prioritize the work for that subject matter and help ensure that things get written when appropriate. They’ll help coordinate the writers that are interested in contributing to that topic and make sure that the docs in that area of the wiki are kept tidy and are properly crosslinked.

Obviously, the first step in switching to this driver model is to get people selected for each of the topic areas. We have a new page on the wiki for this. If you know of a topic area that’s not listed there (or is a large enough subset of one of the ones already there that it should be handled separately), please feel free to add it. Similarly, if you’re interested in being a documentation driver for one of those topics, let me know, or put your name down.

I’ve not yet selected the topics I will drive, other than likely the XUL and XPCOM stuff. I’m waiting to see what others would like to do first (indeed, if anyone else wants those two, feel free to take them from me). My primary goal as always will be to coordinate the overall documentation effort, maintain the site in general, and contribute as needed, in addition to driving whichever topics I wind up with.

If you have questions or would like to volunteer to drive a topic, feel free to comment here, send me email, or pop into #devmo on irc.mozilla.org.

During the Engagement team work week last week, the four on-staff Mozilla developer documentation writers (myself, Janet Swisher, Jean-Yves Perrier, and Will Bamberg) had a sit-down to talk. This was a big deal since it was Jean-Yves’s first time meeting with us in person since joining Mozilla on December 1, and Will’s first time meeting with us since he’s been largely off doing fairly separate stuff documenting the Jetpack SDK.

We had a long discussion about a wide variety of things, and I figured I’d blog about it, to share those ideas and thoughts with the wider Mozilla community — and to flesh out the ideas from the outline format I took the notes in.

Today, let’s talk about our reference documentation and what we can do to improve it.

In this, my final post covering what we talked about during this meeting, we’ll take a look at the new organizational hierarchy we’ve developed for MDN (in a series of previous meetings as well as on a public etherpad), and how we’re going to go about rearranging our content into this new order.

Introducing the new hierarchy

We’ve been talking about fixing MDN’s tendency toward being very shallow, organizationally, for some time. Most MDN content is located right at the top of the hierarchy, making it really disorganized. This is something we want to fix, but work has been slow.

Over the last few weeks, we’ve increasingly discussed this in #devmo, and we finally have a new hierarchy designed that we think will improve things enormously. You can get a look at this on the etherpad we created for the purpose of working it out. There are a few areas where debate is ongoing, but you’ll get the idea of what we’re shooting for.

Making the move

The first step toward moving to this new hierarchy will be to create the new landing pages for each section and subsection, and to revise those that already exist as needed.

We’ll move existing articles as we get to them and as they’re discovered during day-to-day work.

In addition, all new pages should be created in the new hierarchy, once the new landing pages are in place.

Between creating all new content in the right places, and moving old content as we’re able, we’ll gradually make this transition.

On top of that, we can add pages to landing pages even before they get moved, and worry about moving them later if we need to.

A team effort

Because this project is unfortunately not going to be a top priority for the full-time writing team (we’re being kept crazy busy keeping up with the release train!), we’ll be relying pretty heavily on the rest of the MDN community to drive this work forward. Fortunately, it’s something that can be done a bit at a time as community members (and full-time writers) have a moment to spare now and then.

Hopefully you can pitch in and help us make MDN cleaner and easier to navigate!