Jan 222012

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!

 Posted by at 9:00 AM

  4 Responses to “Reorganizing MDN documentation”

  1. I like this idea but was wondering if old URLs will redirect to the new ones? Also, what MDN users have permission to rename/redirect pages?

  2. Yes, old URLs will redirect. And all users have permission to rename, move, and redirect pages.

  3. I think the main reason I prefer shallow hierarchies to deep ones is that I think with deep hierarchies there’s much more room for disagreement about where things belong, which can mean time spent discussing and reorganizing the hierarchy (unless there’s a benevolent dictator who knows exactly where everything belongs).

  4. Perfect example of David Baron’s concern – I see ‘Mobile’ and ‘Web Development’ as top-level items, but I think we really need a good ‘Mobile Web Development’ section.

    It probably depends how strictly we enforce the hierarchy. I lean towards having resilient links and redirects so we can be more loose with the hierarchy. Y’know – like the web. ;)