Jan 172012

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 thing we talked about, since we had Will around, was why Jetpack isn’t documented on MDN and what would be required in order to change that.

Jetpack’s special needs

Right now, there are a few specific reasons why Jetpack’s documentation isn’t on MDN.

First, because the docs are built from code that can be checked out or downloaded by the developer, it’s available offline. Obviously one of our goals for MDN is to eventually support offline usage. However, says Will, this is probably not a deal-breaker for MDN since using the SDK generally requires being online anyway. But it’s still something the loss of which would annoy people.

The other major issue is that the current setup lets users add docs for third-party modules, integrated into the docs on their machine. Jetpack users love this feature and use it frequently. There’s currently no established way to document third-party modules in a way that integrates with MDN content.

Problems and a short-term goal

That all being said, it’s clear that at least for now, Jetpack’s documentation can’t move onto MDN without disrupting a lot of people’s workflow in unhappy ways. So for the time being, we’re going to leave things as-is, with one exception: we’re going to start trying to find good ways to cross-link between the Jetpack docs and the content on MDN where appropriate. This will unfortunately largely be a manual process, but at present, the two documentation sites essentially pretend the other doesn’t exist, and this is entirely unacceptable.

So I’d like to encourage writers contributing to either set of documentation to be sure to link to the other whenever appropriate. This will likely be a slow process, but it needs to be done. If anyone would like to volunteer to work on this on the Jetpack side, please contact Will and he’ll help guide you on your way.

Long-term goals and dreams

Someday, ideally, the Jetpack material will migrate to MDN. That will require some development work and advance planning, most of which can’t realistically happen until well after we complete our migration to Kuma. We’ll be thinking about this a lot over the coming months, and drawing up ideas to send to the Kuma development team, to help drive the development of our new documentation platform in a direction that will make this possible.

One idea we had was obvious enough: set up a place to document third-party Jetpack modules on MDN. This could be done now, except that the Jetpack SDK offers ways to automatically generate documentation. Perhaps we could work with that team to add a button to automatically publish documentation to MDN’s third-party module section.

Another, more involved, notion we had: could the new file system API be used to let you connect locally-hosted Jetpack documentation to MDN in a way that, while not visible to anyone else on the Web, would look integrated to local users? That is, you could have Jetpack documentation on your computer that MDN would (with your permission) detect and present as if it were part of MDN, with some sort of banner indicating that it’s not official content. This could be an interesting experiment, if nothing else. It could also be used for drafting content before publishing it to the rest of the world.

A lot to think about

Obviously, there’s a lot to consider here, and the “good” solutions are going to take time and planning. In the meantime, we’ll keep on working to come up with great solutions while working on fixing the existing lack of inter-linking between MDN and the Jetpack documentation.

 Posted by at 9:00 AM

  One Response to “Documentation and Jetpack”

  1. Using the SDK doesn’t actually require being online – merely using the Add-on Builder does. Somebody who downloaded the SDK can build the add-on on his own machine without having to be online.

    File system API (at least the way it is implemented in Chrome) doesn’t actually give websites access to user’s file system – it’s rather a virtual file system located in a particular directory of the Chrome profile.