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.

Using the CSS Reference as a test platform

Jean-Yves has been working furiously on updating, cleaning up, and enhancing the CSS Reference. He’s experimenting with new ways to format the content, ways to improve usability, and generally doing a lot of amazing stuff there. If you haven’t looked recently, you should.

You’ll find, if you look it over, that he’s doing two things: he’s going through alphabetically, tidying things up and making corrections, and he’s using a few pages to try out new ways to present the content.

These experiments are paying off. We’ll soon have an improved structure for the content of each page, and new, clearer ways to describe the syntax of CSS properties. Each page will offer a link to an explanation of how the syntax descriptions should be parsed.

We’re also going to be experimenting with using tooltips to define technical terms, so you can get them without having to follow links (although links will still be offered).

In addition, it will be easier in the future to navigate the documentation. Right now, once you’re on a page for a particular CSS property, you have to use the back button in your browser to get back to the index. We’ll be adding an index link, and will be looking at options to present an actual index in a sidebar on every reference page.

Spreading out

Once we’ve got the CSS Reference changes nailed down, we’re going to take what we’ve learned from those experiments and apply them to the other references, including (but not limited to):

• DOM Reference
• HTML Element Reference
• SVG Element Reference
• MathML Element Reference

In addition, we’ll continue to work toward removing Gecko-specific content, making our open web documentation browser-agnostic.

MDN everywhere

We’re also working on trying to make as much of our content as possible genuinely usable on mobile devices. Part of this process involves removing cases where we use tables to lay out our text (such as we do on many of our landing pages). We’ll be switching to using CSS columns instead.

Other issues that need to be addressed include how to cleanly present sample code on mobile. These tend to be fairly wide, making them hard to read at best on mobile devices. This is going to be a challenge, but we’re up to the task!

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’m going to share our thoughts about finding and reaching our users.

Who are you and what do you want?

First, you get bonus geek points if you catch the reference I just made.

In order to improve our documentation, we need to know more about who our users are and what they want. There are a few key metrics we need to gather:

• How many users do we really have?
• Is that number growing, and how fast?
• Where are they and are we serving them content they can read?
• What do they look for and do they find it?
• What’s the most popular content? The least popular?
• Is the content any good?

We talked a good bit about the idea of publishing a survey that we can run periodically to get some feedback from our users. We’ll be talking to the metrics team and other teams that have run surveys to get ideas for how to go about this. Jean-Yves is going to be heading this up for us for the time being.

Statistics and metrics: A numbers game

We’d like to start publishing metrics and usage data for our community to read. This is information that can be of enormous use to writers to figure out what content is most important, what content is most in need of work, and what content should be prioritized for localization.

I’ll be talking to our metrics team about creating a dashboard with information about the most viewed content, search statistics, and the like. I’m sure they’ll have great ideas about the types of statistics we can get the most usage out of, and how to go about presenting it.

That information ought to be public, and I’ll be working to make that so.

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.

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.

Let’s start by talking documentation sprints.

Ideas for growing doc sprints

After successfully launching our doc sprints program last year, we have plans to try to make them even better. The ways in which we’ll accomplish that are still a bit up in the air, but we’re working on it. One thing we would like to do is look at the possibility of attaching some of them to MozCamp events; that is, adding a couple of days before or after a MozCamp dedicated to doc sprinting. This would let us share event planning resources with those events, likely saving money and making the preparation easier and quicker.

One thing we do want to do in order to improve the results of future doc sprints is do a better job of setting goals for each event. Janet will continue to spearhead the doc sprints for the time being, and is going to talk to other event planners in the Mozilla community to get ideas for how they go about setting goals. She’s also going to look over the output from past sprints to see how we did and how we can get better.

Doc sprint planning

It may be too late to look at attaching a doc sprint to the Buenos Aires MozCamp taking place in April; however, we can and should look into future MozCamp events to see if we can do that.

In addition, when we don’t attach to MozCamps, we would like to make use of Mozilla Spaces whenever possible. This would help bring Mozillians together in a great way, and would help give our writers and volunteers more access to engineers in a lot of cases. Right now, the most likely candidates for this are obviously Mountain View and Toronto, but as we build out more Spaces, this list will grow.

We’ll also be continuing to alternate between virtual and in-person sprints. In fact, our next virtual sprint is in a week: from January 20-21.

Helping communities run their own doc sprints

We also want to encourage local communities to hold their own doc sprint events. These can be either general documentation events, where local teams of folks get together to write new content, or localization events, where regional groups of Mozillians come together to translate content. Both of these kinds of local events are worthwhile goals, and we want to be sure to encourage that.

One way we’re going to do that is by assembling a documentation sprint planning guide. This will provide information about how to announce, organize, and manage doc sprints. It’ll also provide tips on finding a location (such as how to arrange to use a Mozilla Space, for example, or how to find another site if your local area doesn’t have one). On top of that, information will be provided as to how to get swag to hand out to participants and how to promote your event.

In addition, at least sometimes, we can help get subject-matter experts involved, especially when there are some already in your area.

The community of Mozillian writers and translators is growing, and my goal as the doc team lead is to ensure it keeps doing that, partly through helping organize things, but at least as importantly by enabling other Mozillians to continue to push our already great documentation forward. Let’s make 2012 a great year by working together!