Wikis instead of product documentation?

John Udell suggests here (link by way of Tim Bray) that technology products should use wikis as documentation and let users fill it up with tips, tricks, problems and workarounds; he calls it “Open Source Documentation.” He makes an excellent argument, and I can already point at one software company who has this nailed.

Atlassian Software maintains a wiki for both of their products, and as a customer I can vouch that they’re tremendously useful. (Take a look here at the documentation wiki for Confluence.) There are two reasons, I think, that they work so well:

First, Atlassian writes good documentation out of the gate. John says that we should leave everything up to the users. I disagree. But keeping the canonical documentation in a wiki is smart: unlike paper or CDs, the documentation stays alive, growing and accurate. The users always see the most recent, accurate information. But more than that, they can expand and elaborate the wiki with their own experiences in the field.

Second, the Atlassian developers communicate aggressively over all sorts of channels: discussion forums, email, support tickets, and yes, the wikis. Sure, it’s great when a user can help another user — that happens frequently. But devs have access to information and knowledge that regular users don’t. And they can often find answers more efficiently than anyone else. It’s imperative that they participate in the conversation — helping out where they can and adding to the base of shared knowledge.

It’s been argued that asking highly-paid developers to spend energy answering user questions is a waste of time and money. But as a developer, I think it’s an incredibly beneficial practice: an immediate and brutal feedback mechanism. It forces us to deal with the repercussions of the decisions we make each day; the applications we code, the interfaces we design, the documentation we write. It makes us better developers. I admit, there may be a point at which scale makes this impossible, but I think the majority of development teams are small enough that they could benefit.