Death By Wiki

One the biggest software concepts of the past decade is the wiki. It's a really great concept that should have been invented 15 years ago. We had the technology, but it took Ward Cunningham to figure it out. Yay Ward!

A wiki allows almost anyone to contribute to a project, and you get instant gratification when you do. If you're reading a page, and see a typo, you can edit the page yourself, without waiting for a blessing from above. Once you edit the page, then your edited page becomes the page everyone else sees. Lookie what I did!

Unfortunately one of the biggest strengths of the wiki is also it's Achilles' heel. The great unwashed masses can maintain it, so, too often, the great unwashed masses are left to maintain it. That doesn't work.

Projects need leadership. The leadership needs to hop out of the ivory towers now and then and spend some time hanging out with the peasants and documentation.

I know it's boring. I'd rather be spend time writing code than documentation. Almost everyone would, but the docs got to be done.

I'm seeing more and more projects that aren't really projects. They're just inbred code excretions. A new version of the code comes out, and you have no idea what it does, or how to use it. Those in the know know how to use it, but the rest of us are stranded.

In the inbreeder's mind once the project becomes popular someone will swan in and write the documentation. Sometimes it's even worse and they try to make a virtue out of bad documentation by claiming that anyone that uses their code is a l33t h@x0rs and should read the source code.

Adding to the problem, a project opens up a wiki. This is supposed to magically fix all the documentation problems. Users are supposed to gather like worker bees and create documentation. The problem is that one user can't tell if another user's solution is good or a bad. They have no high level view of the project.

For a wiki to work, the project heads need to invest time in checking what the wiki writers are writing. If someone puts something up that's a bad idea, it needs to be edited out and the writers need to know why. If it's a good idea, it needs to get official praise so other users know it's a valid solution.

There also needs to be an editor who chops out entries that are no longer relevant. If version 2 has a bug, and version 3 fixes it, then a 2 page discussion on the version 2 bug is no longer needed. Especially when the current code is version 10 and version 2 hasn't existed for 5 years.

Wikis are a great tool for empowering non-technical users, but they're not babysitters. If you write code for others, you have to listen to them. If you don't you'll find your babysitter goes psycho and your project will die from "shaken code" syndrome.