Jan 092008

Lately I’ve been thinking that one way to improve the quality of our documentation would be to have volunteers “take charge” of various topics in the documentation.  Basically, the idea would be that someone with actual knowledge of a subject would take on the job of ensuring that the documentation covering that topic is accurate.

As the documentation lead, I find myself becoming a generalist.  I know just enough about everything that I can spot the blindingly obvious errors, but the subtle stuff tends to escape me.  It would be helpful if we had some experts to cover specific “hot spots” of information.

Even if these experts are only tasked with reviewing changes to ensure their factual accuracy, that would be a huge help, I think.  Ideally they’d also be contributing new content as necessary, too, but just having someone that knows the subject matter do regular reviews would be awesome.

What do you think?

 Posted by at 7:19 PM

  3 Responses to “Making documentation more orderly”

  1. If there are people with both the knowledge and the time to do this, I think it would be very good for the quality of the documentation!

  2. Sounds like what is already done.

    I know I check the recent changes dating back to my last visit and specifically look for changes to the pages I’m most concerned with, and it appears others do the same; you’ve got “interface people” targeting the interfaces and Jason Orendorff in particular doing the same with the JSAPI docs.

    In consideration of that, the closest thing to what you describe that would be a change from how things are done now would be to have some sort of formal “owner” to oversee changes made to their respective documentation topics, but I don’t think activity at MDC is high—or chaotic—enough for that to be necessary.

  3. Well, there are a couple people that keep an eye on things, but most of the documentation does not go through any kind of technical review process, which it really needs to. We have people who are writing interface documentation but in only a few cases is anyone actually reviewing them to be sure they’re actually accurate.

    Just getting it written isn’t enough — people who know and use the technologies being documented need to read the docs and fix the errors, or at least let someone know about them so they can be fixed as quickly as possible.