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.
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):
In addition, we’ll continue to work toward removing Gecko-specific content, making our open web documentation browser-agnostic.
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!