Bit Stampede

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!

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, I’ll be sharing the results of our discussion about the impending Kuma migration and what will come next.

Scripts and templates

The next Big Thing that needs to happen in Kuma’s ongoing development process is to implement support for the type of scripted templates we use pretty frequently on MDN. One of my goals for when I resume work after this week I’m taking off (I do so love scheduled automated posting in WordPress) is to go through our existing templates and figure out the types of things we need to be able to do, to get those prioritized for the development team.

It’s almost certain that we’ll be using server-side JavaScript rather than the Lua-derived DekiScript language currently used by MDN’s MindTouch based wiki. That means we’ll need to update our existing templates. It’s possible some sort of automation might be done for that, but realistically, I don’t expect that to happen (and if it does, there will certainly be a need to review and hand-tweak stuff in at least some cases).

That said, this will be a great opportunity to look at all our templates, figure out which ones we don’t really use anymore, and get rid of them. In addition, we can clean up existing templates to work better, be smarter, and integrate localization support in templates that don’t currently have it.

Future development

We need to be ready for the future. The initial deployment of MDN on Kuma will not have all the features we want. Indeed, it won’t even have all the features we already have, although it should have most of the ones we use regularly. As such, we need to be sure we have bugs filed to give the development team a solid set of things to be done going forward.

Among other things, we’ll want to be able to have live examples embedded in documentation, so you can see how things work without having to click a link to a separate page. These should support HTML, CSS, JavaScript, and all the web goodness we love so much.

We need support for server-side components, so that examples for XMLHttpRequest, WebSockets, and the like can be run without needing to host stuff outside Mozilla’s servers.

We’d like features to make it easy to integrate documentation content with IDEs and other utilities, as well as to make it easier for scraping tools to peel out content to present in other formats.

We want offline access to the content, either by publishing sections of the site as PDF or by making it easy to download chunks of the site in HTML form.

We need good localization tools, such as dashboards of content in need of translating, support for comparing the English and translated versions of a page to find the areas that need reviewing, and so forth.

Let’s make it happen!

We’ll be making sure we have a prioritized set of features to guide the developers toward making Kuma a platform that serves our needs as well as possible. If you have ideas for features the Kuma platform could have to make our lives better, please share them.

This is our chance to have as near-perfect a platform for our documentation as possible! It will take time to get there, but we’ll do our best to make it happen!

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.

One area we spent a lot of time talking was about automation and how little of it we currently do when creating documentation.

One-way generation of documentation

Right now, there’s a Firefox extension by Trevor Hobson that we can use to do one-time generation of reference documentation from IDL. This has been a great tool for us but isn’t an ideal solution for a couple of reasons:

1. It uses MXR to get the code and tries to use that to differentiate between releases. This used to work great but no longer does since we don’t create a new branch for every release anymore.
2. It only works for IDL; it can’t parse C header files or JavaScript code modules.
3. It only works once. Once the article is generated, all future revisions must be done by hand, unless you’re willing to lose any edits you’ve made to the article in the interim.
4. It only works one-way. Once you’ve made changes to the article, you can’t get those back into the IDL.

Two-way documentation sync: A dream within a dream

Our dream — and it may be an impossible one, or at least extremely unlikely — is the notion of being able to do two-way synchronization of reference documentation back and forth between the wiki and the source. This would obviously involve a lot of code to manage, and getting resources to create something like this is unlikely anytime soon.

The idea is that you could pull content into the wiki from comments in headers and the like, and then use the wiki to edit that content, publishing patches back to be pushed to the tree in an automated fashion after some sort of review. Likewise, periodically, the documentation would be refreshed based on changes made to the headers.

The details would have to be worked out, obviously, but this is a fascinating idea that, if it could be perfected, could make our reference documentation not only easier to maintain, but would help the writers make sure the comments in the headers were kept accurate and tidy.

Automation and localization: A conundrum

Obviously, in-source documentation is inherently unfriendly toward localization. You don’t want to clutter up the code with multiple translations of the content, so localized content would have to be maintained separately. Automated content would only be in English; all localizations would likely, unfortunately, need to be done manually. However, we might be able to mitigate that somewhat. If the editing of automated docs were more structured than the current free-flow system we have (that is, if each method, for instance, were edited as individual components rather than as part of a whole, for example), it would be relatively easy to pull in just the changed stuff and know exactly what needs translating, quite easily.

It’s been suggested that, at least for younger folks outside the English-speaking parts of the world, reference documentation being only (or primarily) in English isn’t an issue since they learn it in school anyway. However, older users may have little if any English. Either way, having translated material is usually preferable, at least to some folks, as long as it’s accurate and current.

Talk about planning ahead!

There are a lot of things to think about when automation is involved, and we’ll be talking about this more in the future. Given that a lot of this is extremely far-forward looking, there’s no rush here! Let’s think about it and get it right.