Day of the Wiki – web2project

I have to say that one of the best – yet often under-utilized – tools available to teams right now is a wiki. I happen to prefer MediaWiki, but there are numerous options out there. In preparation for the pending web2project release, I've spent a good amount of time getting our wiki prepared. What follows is a quick rundown of what I've done and what you can probably do on your projects… Open Source or not. 😉

First, you need to have a plan in mind. Lots people people are willing to contirbute small tweaks and adjustments to wikis but they're not willing to undertake large efforts unless they're invested in the project or topic. Make it as easy as possible for them to make those little tweaks. Most people like structure, they like to know that they're doing things "within the rules", so make the rules and structure clear. The handful of changes that don't meet the rules are easy to detect… that's what the Recent Changes page is built for.

Next, you need to decide what will be in it. No, you don't need to have every single page figured out. More than anything, you need to know your big areas of interest. For web2project, I've split this into Core and Add On Modules. And yes, this is identical to the structure I set up for dotProject in late 2006. There are likely to be additional areas of interest as we go, but this is enough to get started. Once again, making revisions is the point of a wiki.

Next, you need to decide what is not going to be there. At some point, someone in your organization is going to come up with something sort of related to add. And then there's another idea and another idea and before you know it, you have a wiki with literally hundreds of pages of information that is steadily growing stale… or worse, someone has to keep it up to date. An easy rule of thumb… if it doesn't promote the understanding of somthing fundamental to your project, don't worry about it. Most likely anyone who has found your wiki can use Google.

Finally, you need to take guesses on who will use this documentation. Is this entirely for Developers? Is it for Users? Is it for system admins or sales? Each group is going to browse and want to look a the information a bit differently. That doesn't mean you have to work to appeal to each group, but it does mean you can make their lives easier. With one of my customers, each installation of an application had a page. And each page was linked to a number of Categories… the application itself, the specific version of the application, the server it was on, and what product line it was. This gave Sales a way to say "who is using Product X?" while a System admin could as "What is running on server B?" It's a simple but powerful concept.

So here are the points I'm leaving you with…

Who is using your wiki? How are they using it? What are they trying to find? Did they find it? Did they have to dig through a bunch of crap to get to it?