Oct 052012

Note: You may see “documentation process” and think this doesn’t apply to you. You’re almost certainly wrong! If you contribute to the Mozilla project, this almost certainly does apply to you, so please read on!

The short version

Because the rate of development at Mozilla is accelerating faster than the MDN developer documentation team can keep up, it’s time for us to establish a process by which development teams request that the documentation team produce content to cover new features, APIs, and technologies. I have produced a document that outlines a proposed new process by which this will be done, outlining how documentation requests will be handled and prioritized, how we will interact with the developers, and the responsibilities of the writers and the developers in terms of getting the documentation produced.

The long version

Mozilla developers rock. Like… they rock hard. Odds are, if you’re reading this, you’re one of those amazing developers. If you are, you need to understand, first off, that the MDN team knows you’re almost frighteningly good at what you do.

Because of that, we’re totally swamped! With so many amazing new technologies and APIs coming from your keyboards to our to-do lists, we simply can’t keep up. As Mozilla has grown, the amount of material that the developer documentation team needs to produce has skyrocketed. Think about it: we’re documenting one of the most popular Web browsers in the world, a popular e-mail client, open Web standards from HTML through CSS and JavaScript to new technologies like WebAPI, how to write games and apps online, a brand new mobile operating system (Firefox OS), concepts like security, identify management, and the like, and more.

And we do it with a paid staff of four full-time and one part-time writer and a community of contributors who, while amazing, can’t always have the time to document this much cool stuff.

Most large organizations that have technical documentation requirements have a process by which that happens. Mozilla never has; we’ve done our documentation in a very free-form way: a writer sees something needs to be documented and writes about it. A lot of things fall through the cracks because the writers didn’t know they existed, or were ready for documenting.

The time has come for that to change. In an attempt to improve the responsiveness of the documentation team, increase both the quality and the quantity of material we can produce, and help enhance communication between the development and writing teams, I have proposed a documentation process by which development teams will request that writers produce material for their work.

I urge you, if you contribute to Mozilla, to read the proposal and offer your thoughts. I think this will help everyone. Our developers will see their work get properly documented both better and more quickly. Our writers will be able to avoid wasting a lot of time searching for information they shouldn’t have to search for. And our users will get top-notch documentation for the amazing Web of the future.

To offer your feedback, you may either post to the mozilla.dev.mdc mailing list, send me email, or comment on this blog post.

 Posted by at 9:26 AM