Open source documentation

On Christmas day, after the potlatch subsided, I headed out for a run. But when I flicked on my MP3 player, I heard...nothing. Glancing down at the display of the Creative Nomad MuVo TX I saw an unwelcome message: "File system error." Grrr. Back inside, I dug into the problem. The Creative 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, since 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.

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?


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.


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? Its such a crazy idea that it just might work. [Full story at]

In his comment on this column, Tim Bray notes that Wikipedia needn't host the information. And indeed, there are a number of Wiki-based support sites out there. Ken Tompkins pointed me to the Tinderbox Wiki. There's a Mozilla Wiki. Jonathan Nolen notes that Atlassian Software -- whose enterprise Wiki Confluence I have been remiss in not mentioning along with others I've written about lately -- eats its own dogfood when it comes to Wiki-based support docs.

These are great models, I'm sure there are others I haven't mentioned, and I'd love to see the idea spread. Here's something I've been wondering about, though. Suppose that Creative Labs, whose product triggered this column, and LG, whose product triggered that one, ran Wiki-style support sites. Would they own the content? If I contributed, would I just be helping them lay off tech writers? If they orphan those products, what happens to the support sites?

These are mainly non-issues for open source software. But for commercial mass-market products? The reality that users and vendors are partners in the documentation process doesn't entitle vendors to a free pass. In cases where users wind up bearing much of the burden, it may indeed matter, not so much where the content lives, but under what licensing agreement it is created and maintained. It'll be fascinating to see if this issue is put to the test in 2005.

Former URL: