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.

2 Comments »

  1. The number of changes I make to devmo has fallen to almost zero since it switched to dekiwiki. Spending ten minutes fighting with the editing tools just to get a one line change is pretty discouraging. Not to mention the editing UI is slow as molasses. If you guys fix these, I’ll bet you’ll see a significant uptick not just in new contributors but also in old timers coming back.

    Phil

    Comment by Philip Chee — 31.01.11 @ 08:58

  2. I’m not going to argue the basic point, although “significant uptake” is more than I would expect to happen. I don’t much like the new interface either — just give me a text box and let me mark it up manually.

    As I understand it the wiki software is going to be overhauled at some point and replaced with something with MediaWiki syntax, which will make a fair number of people happier, I think. I don’t remember whether that future wiki is supposed to have rich-text editing functionality or not, but I suspect it will in some form or another.

    Comment by Jeff — 31.01.11 @ 10:06

RSS feed for comments on this post. TrackBack URI

Leave a comment

HTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>