The Trouble with Wiki

If the comments don't match the code, they're both wrong.

I've been thinking about this maxim a lot. I recently started a new job, and have been busy learning the codebase. One of the tools that I've been using is the corporate wiki, and once again I'm faced with “wiki rot”: pages that are no longer relevant, or have broken links, or were started with the best of intention and then abandoned. I suppose I should feel lucky: I know one company that stored status reports in their wiki; the chance of a search returning anything useful at that company was pretty low.

Don't get me wrong. I think that wikis were a great invention. Wikipedia is my first stop for answers on a wide range of topics. And I learned much of what I know about patterns and Agile methodology from Ward's wiki (although by the time I started reading, much of the original community had seemingly vanished, replaced by a lot of insecure whiners).

At its best, a wiki gives you a place to write notes that can be shared within a team. It's a natural transition from the “project notebook” that Brooks recommended in The Mythical Man Month. But as long-term project documentation? Not so good.

Projects evolve, and all too often wiki pages don't. After all, the people who spend their days working on a project know how it works. They know the environment variables required for a successful build, and the configuration needed for a successful run. And when new people join the project, it's easier (once you realize the wiki is wrong) to just ask someone. And no-one has time to update the wiki …

What's to be done? Wikipedia has one answer: a large community of people who passionately update pages. But the key word there is “large.” In a corporate environment, you simply don't have this community. And if you have a corporate practice of putting everything into the wiki, it's not going to be useful even if you do have a community of dedicated maintainers.

I think that a solution for corporate wikis starts with organization by project or product rather than organizational unit. This change is subtle, meant to tap into the developers' feelings of craftsmanship: “these pages are the public face of my work.” An empty project wiki stares team members in the face in the same way “fixme” comments do in code — admittedly, that doesn't work for all teams.

A second, perhaps more important step is to archive all pages that haven't been edited in the last year. Keep them available, but not easily available: don't show them in basic searches, and highlight any links from other pages. In the best case, this will prompt team members to keep their pages up-to-date. In the worst, it will keep casual users from wasting time with incorrect documentation — which is valuable in itself.