Using Wikis with software developers

There’s a lot of excitement lately about wikis. Wikis are an amazing tool, but the hype can lead some to think that simply installing a wiki and letting people do what they want with it will be effective. I fell for the hype and installed a wiki for my team to use. But my wiki was ignored by pretty much everyone, and fell into disuse. Recently, I relaunched the wiki concept within my team, this time successfully. What changed?


Start off maintaining existing documents
What is this Wiki thing for? That’s the question most of your team members will be asking when faced with your new-fangled Wiki. Over time an enthusiastic group may evolve uses for a Wiki, but the initial reason to learn a new tool must be something pretty specific and practical.
Maintaining documents that have to be maintained by somebody anyway is a good start. Since the documents have to be maintained anyway, you’re not creating extra work for anyone by asking them to use the wiki. In the Wiki that the MindCanvas dev team uses, we started with the following documents:

Build Instructions
Installation Instructions
Demo Script
Testing Procedures for New Releases
Instructions for how to branch in source control system.

These are bread-and-butter documents, documents that need to be maintained within an organization anyway. Maintaining these documents in a Wiki instead of a word document is an easy sell, a quick win.
Make it easy to login
The first time I tried to deploy a wiki, it was installed on my public website, and protected by a login and password. Every time I would try to ask someone to do something on the wiki, they would ask me “what’s the login?”. The fact is that anyone who uses a computer has too many userids and passwords to remember. Adding one more is an extra source of friction, another failure point on the path to wiki adoption. You don’t need that!
The second time I tried to use a wiki, I used the “writeboards” that are part of basecamp. Since I was using a wiki that was part of my existing project management software, there were no additional passwords to remember. Resistence was futile.
Insist on Wysiwig
This is the main failure point that we haven’t solved yet. No one on my team is very interested in learning the syntax of wikis. Is this surprising? Not really. Everyone has a lot of work to do already, and wiki syntax is a useless skill in the larger scheme of things. As a result, our wiki documents tend to be pretty ugly, and not very well formatted.
A wysiwig wiki editor would solve this problem. Most vendors (like jotspot and socialtext) have done a good job with this. Hopefully basecamp will catch up in the near future.