31.01.11

Waiting for Superman

Tags: , , — Jeff @ 02:20

Hacks (if you’re into web developer-y things: subscribe!) has a post on the latest MDN sprint, a well-attended event with many fresh faces. This bodes well for Mozilla documentation. Sheppy always has more docs to write than time to write them. Even with recent help, there’s too much for documentation writers at Mozilla-the-corporation to handle. But Mozilla-the-community can get it done if people are willing to do it.

Yet there’s the rub: if. Some people who could absolutely kill writing documentation instead write patches, curate mailing lists or forums, run IRC channels, or translate. It’s no given that there will be writers sufficient to the tasks at hand. Even if there are, what will they choose to document? Will they write about ooh, shiny! or about technologies more abbreviation than word? Docs will probably get written, but it might take awhile, particularly if the change is hard to grok in short order.

Who will write critical documentation for your next great fix if Mozilla-the-corporation lacks the writers and Mozilla-the-community chooses to work on other important tasks?

You.

There is no cavalry, no Superman to save the day.

You know the technology in question, the nature of the fix. You’re the person who can best explain what you did. You don’t need to have the change explained to you in order to document it. The person uniquely suited to documenting your fix is you.

Maybe you’re not the best writer. Take a stab anyway. Write something hackish and dump it in a user sub-page, then mention it in the relevant bug when you add the dev-doc-needed keyword. Or edit the relevant page and ping a good writer for a once-over.

You know the ins and outs of the change. The expert writer doesn’t. Write up the change if you can. But if you can’t, just getting it out there, even in an unpolished state, makes it vastly easier for him to translate your expert knowledge into expert documentation.