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, 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.

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.

This time, I’m going to talk about our plans for documenting BrowserID.

What it is and where we are

BrowserID is a new, open, identity system developed at Mozilla that makes it easier to sign in to lots of web sites using just your email address and a single password. Any site that supports BrowserID can then query a BrowserID identification server to determine if you’ve correctly authenticated.

Right now, what BrowserID developer docs that exist are slapped onto Github along with the code. That’s been good enough while BrowserID was in development, but now that it’s starting to try to get more broadly deployed, it’s time to get the documentation whipped into proper shape and up on MDN.

Where we’re going and how we’ll get there

Will Bamberg will be heading up work on the new MDN landing page for BrowserID content starting soon; a stub is currently in place with no content. Will is going to be drafting up the content for that page soon so it can be reviewed and tidied up before content starts to be added to the site.

A “BrowserID field guide,” which covers how to go about making a site use BrowserID for authentication, will likely be the first content added to MDN. After that, an API reference and further examples will be created. We’ll also have links to plugins for popular web apps and other popular web site software (such as the BrowserID WordPress plugin).

We’re pretty excited about BrowserID, and looking forward to having really great content to help web developers start using it to authenticate their users in an incredibly painless way.

As you work on Mozilla, you’ll often file bugs or submit patches that will involve changes needing to be made to the documentation on MDN. I’ve written an article on MDN about this issue, and I’m duplicating it here to get it in front of more people that need this information.

Flag your bugs

When you file a bug that, upon resolution, will likely require that documentation be updated, you should add the dev-doc-needed keyword to the bug:

You don’t need to wait until the bug is fixed. Indeed, it’s easiest for the doc team if you add this keyword well in advance of the bug being resolved. That lets us plan ahead. That said, it’s never too late to apply dev-doc-needed to your bugs!

Also, note that if you use the addon-compat keyword to flag that a bug will impact add-on compatibility, you should absolutely also add dev-doc-needed!

The writing team uses Bugzilla queries, as well as a special documentation tracking site that interfaces with Bugzilla, to track our work. By using dev-doc-needed, your bugs will get brought to our attention at the right time to ensure the best odds that your stuff will be written up in a timely manner.

When the bug’s contents are documented, the person that did the work will replace the dev-doc-needed keyword with dev-doc-complete and, ideally, add a comment to the bug with links to the pages that were updated or created to cover the bug’s contents. You should try to review the changes to ensure that the writer got things right.

Indeed, if you love Mozilla, you’ll be sure you’re available to help out if the writer has questions. They may contact you by email, or post questions as comments on the bug. Try to take a few moments out of your busy day to answer questions.

Provide information to the writers

That brings us to the next point. Not only should you be sure to answer questions the writers bring to you, but a little simple preparation can stave off a lot of back and forth. Try to add a note to the bug that indicates exactly what needs documenting. A lot of bugs have pretty cryptic descriptions, or the actual documentation issue at hand isn’t obvious from the bug’s description.

For example, a bug might have a summary like “foobar.com doesn’t work in Firefox 45″. There may then be pages and pages of comments where the problem is debated, possible solutions suggested, and so forth, followed by the bug eventually being marked as resolved. With no other information, the hapless writer is left to pore over all those comments and the patches, hoping to figure out what needs documenting.

When the patch is finally checked in, you should try to add a comment that summarizes what the final resolution was. This can be either “Writers: check out comment 32″ if there’s already a comment that explains the final resolution, or a quick summary of what’s changed, like “Check out the new method and attributes in nsISomeInterface” or “We added the someStandardDOMMethod” method to DOM elements”. Doing this can save the writers a lot of time (time that could better be spent writing even more stuff), and can save you from having to answer pesky questions.

It’s also helpful, of course, if your bug includes a link to the specification or design document for the feature being affected by the patch.

Just having directions on where in the code to look, or what subtle change has occurred, can make all the difference between your change being documented quickly and having it languish for a long time because it scares the writers off.

What if there’s not a bug for it?

Sometimes, you notice something’s wrong with the documentation. Maybe there’s a missing article, or you realize we need a guide on how to use some technology, and there doesn’t seem to be one. You can, of course, write it yourself. But if that doesn’t work for you, feel free to file a bug against the Documentation Requests product on the Mozilla Developer Network component on Bugzilla.

Feel free to update the documentation yourself

MDN is a wiki! You can log in and update the documentation yourself. A lot of programmers don’t consider themselves up to the task of writing documentation, or are crazy busy, and that’s okay! That’s why we have writers, and that’s why we have all the above tips.

However, if you have a few minutes, and feel comfortable doing it, feel free to log in and apply the necessary fixes yourself. This is often really simple for minor changes to the behavior of something, and can possibly save everyone time and effort.

For that matter, if you have the time to jot down relatively thorough notes about your change, you can toss them into the bug, or add them to the wiki. Our happy, helpful documentation gnomes live to clean up your writing, so don’t be afraid to try.

Ask for help!

If you’re not sure how to get something handled in documentation, or are trying to update the docs and are stuck, feel free to pop into #devmo on IRC, where the doc team hangs out, or ask questions on the documentation newsgroup.