Open source documentation

On Christmas day, after the potlatch subsided, I headed out for a run. When I flicked on my MP3 player, however, I heard ... nothing. Glancing down at the display of my Creative Nomad MuVo TX I saw an unwelcome message: "File system error." Grrr.

Free IT resource TechNet: More ways to know it, share it, and keep it running. Sponsored by Microsoft Free IT resource Attend the SOA Executive Forum: Breaking SOA Bottlenecks SOAExecForum.com/may2007 Sponsored by InfoWorld

Back inside, I dug into the problem. The Creative Technology support page was, naturally, of no use whatsoever. So I turned to Google and found a handful of postings, on various forums, in which users reported similar experiences.

Some folks were able to reformat the file system. That was no help to me, though, because I couldn't even mount the device. Others said the only recourse was to return it for a replacement. I'll bet a geekless household somewhere absorbed this bitter message and did just that, but I wasn't ready to give up. Still other forum postings suggested that a firmware upgrade might save the day. Sure enough it did, and I was out the door again.

What had caused the problem? Miscegenation, I think. I'd previously used the device only with my Mac. But earlier that day, I'd plugged it into a Windows machine for the first time. After seeing some minor errors, I switched back to the Mac. All this promiscuous platform-switching must have scrambled the poor thing's little brain.

As I jogged the empty streets I asked myself two questions. How can high-tech product support be so abysmally bad? And how did we arrive at the point where users, not vendors, provide so much of the useful information?

A couple of tuneful miles later, my annoyance faded into enlightenment. In a perfect world, products would be fully tested and work-arounds for bugs would be carefully documented on vendors' Web sites. In our world, though, I'm not willing to pay $500 for a MuVo or $1500 for an iPod. Something's got to give; and so when things go wrong, users turn to one another for help.

This isn't necessarily a bad thing. Collectively, we users know a lot more about products than vendors do. We eventually stumble across every undocumented feature or quirk. We like to maintain the health of the products we've bought and we're happy to discuss how to do that with other users.

The problem is that vendors, for the most part, do a lousy job of encouraging and organizing those discussions. Here's an experiment I'd like to see someone try: Start a Wikipedia page for your product. Populate it with basic factual information, point users there, then step back and let the garden grow. Intervene only to repair vandalism, make corrections, and contribute useful new facts.

You could, of course, host your own Wiki site for this purpose, but I don't think the dynamic would be the same. As I write this column, I'm watching the Wikipedia's page on the Indian Ocean earthquake and tsunamis -- specifically, the change history page -- which is receiving updates and minor corrections at the rate of one every few seconds. That outpouring of collaborative energy is, of course, galvanized by a horrifying global event. For a million lesser topics, the Wikipedia shows us, thousands of times every day, that people can and will create decent documentation. The fact that nobody owns the stuff is a feature, not a bug.

As users of high-tech products, we're already responsible for writing a lot of our own documentation. Might we use Wikipedia to consolidate our efforts? It's such a crazy idea that it just might work.