How (not) to turn your wiki into a cesspool

A few thoughts on what doesn't belong in a wiki, where developer documentation should live and why the wiki shouldn't be its source of truth.

Does every company wiki turn into a cesspool? How many times have I seen a wiki, after a few years of use, turn into a cesspool ripe for a thorough cleanup? We use Confluence at GoodData and used TWiki at Systinet, and it always ended in the same disaster. The problem is probably how people use the tool. The great thing about wikis is how easily you can write pages and link them together. That strength is also their greatest weakness. As the saying goes, live by the sword, die by the sword. When writing a wiki page is so easy, people start using it for short-lived documents too. Think implementation analyses, notes on using various tools and their options, or a backlog of half-formed ideas. Of course nobody updates those documents, and when people need current information they write new documents that cover the same ground. Every search becomes an archaeological dig with a full-text search and no guarantee of finding anything. A few rules can keep a wiki in shape.

Some kinds of information simply don't belong in a wiki. That includes material with a limited shelf life, such as the implementation analyses I mentioned. A wiki shouldn't be the source of truth for information that changes often. Different groups of users go to the wiki for different things. Developer documentation in particular, such as designs or instructions for using libraries and tools, should live as close to the source code as possible. Ideally I'd keep it in a version control system such as Git or Subversion and export it to the wiki during the build. That way the wiki stays current, and developers can easily get to the documentation and edit it.

If you use GitHub, you already have the right tools. GitHub supports the Markdown markup language and renders Markdown files directly. You can attach the export and conversion into your wiki's format to a post-commit hook. Checking that the documentation is up to date can then be part of code review.