The wiki trap

Or: "Yo Dawg, I put a wiki in your wiki, so you can point to the wiki that points to your wiki."

A lot of projects use a wiki as a central repository for information about the project, which can be a blessing or a curse. I'll refrain from naming the specific project and wiki, but condensed, I recently had a discussion that went a bit like this:

A: Hey, I need to know how to do X, and more generally what the policy on Y is.

B: It's on the wiki. Look here <>.

A: No it's not, I've been there and it talks about the subject, but does not actually say how to do X.

B: Well then it should be, and I don't know either. It's a wiki, so please improve it.

A: Sure, but I can't if I don't know how to do X.

B: Please ask C.

A: Hi C, I need to know how to do X, and more generally what the policy on Y is.

C: It's on the wiki. Look here <>.

This went on for at least 3 rounds, until I finally found someone who actually knew the procedure and policy. He extensively explained it (thanks, btw), and then ended with:

You should have found this on the wiki.

After that I was, to put it mildly, a bit miffed.

Everyone was of course right, it should have been on that wiki, since that wiki was the project's central repository for exactly this kind of information. I'm quite sure I'm far from the only one who has had this experience. I've been thinking about it for a bit, an here's my impression of the general misconceptions on wikis, and the things you need to realize when you decide to use one.

Wikis are not magic

A wiki can be a powerful tool; all information instantly available, everyone with access can improve upon it, and since history is retained, erroneous additions and alterations can easily be put back. But they are not magic. Setting up a wiki for your project or company does not mean you will automatically end up with all information everyone needs.

Wikis do not reduce the amount of work

Somehow, it seems that people are under the impression that a wiki takes less work than 'traditional' forms of (internal) documentation. This is not true. If anything, on the whole a wiki takes more work; the major difference is that this work can be distributed better over the group of people that need and use it.

Wikis do not stay up to date

This might be the biggest problem. Wikis do not stay up to date. They age as easily as other forms of documentation. In fact, it's quite easy to add information in a place that might not easily be found by someone who wants to update it, prompting them to add it somewhere else. And then you'e even worse off. Once you have found a piece of information somewhere, do you check through the rest of it to see if anything else is more recent?

So while a wiki can be a powerful tool, it can also just as easily (or even more easily) transform into a rotten mess, where information is missing, unfindable, contradictory, or plain wrong.

So how does one prevent this?

Use it. Seriously.

The first step, even before you actually start using a wiki, is to decide to use it. And by use it, I don't mean install some software, put in some starters, and declare that this is now the Official Way. When I say use it, I mean use it. Everyone involved in the project should commit to writing, reading, and updating. Especially in the beginning, or once you have come to the realization that your wiki is a jumbled mess of loose pages, contradictory information and indecipherable explanations, make sure everyone commits to use it. Daily. For everything that is related to the information in it. Even if they are quite sure they know it, they should still check the site if the information there matches their view of it.

The point here is not just to get the wrong bits out and the right bits in. The point is to engrain everyone involved with the notion that this is an integral part of the process. Things change. Processes change, requirements change, and the wiki is the place where you decided this information should be should change with it. This really only goes right once it is such a central notion that you don't really have to realize it anymore, and the checking and updating of small things does happen automatically.

Have some structure

Second important thing is to have a Plan. You'll need a wide overview on what information is supposed to go in, and where it should go. One of the powerful features is that you do not have to design for every little detail, since the users can add those themselves, but you do have to come up with the global structure. If it is not quickly clear where one is supposed to put a piece of information, they will put it where it 'seems right'. And a lot of different 'seems rights' can get very wrong. But if you have the right basic structure in place, things tend to fall into place much more easily. In the end, this will ease up both searching for information and updating it.

Update it

And the third one, if something is changed, make it a task for someone to update the wiki on that regard. If something is decided by multiple people (like in a meeting), immediately discuss who should update the information. If something is decided by someone by himself, he is responsible for updating it. This too goes much easier once the first stap has been done; it should happen automatically, but still explicitely.

Take time every once in a while to get a feel of the overall structure. Call it a structural review, if you will. Sit down with someone else and try to find random bits of information. Click through it and see if things seem out of place. Clear your mind for this, it's quite easy to miss things that are weird but you have gotten used to.

A wiki is not a static piece of design; it's not supposed to. You don't need to look into every little change to see if it's right. And its power comes from exactly that. But like a lot of things, it does need a little careful grooming for it not to become one giant mess. And if it is regularly tended to, it can approach what seems like magic. Fairies will fly by and sprinkle your documentation with magical information-dust. And all live happily ever after.

Oh, and yes, I have updated that original page :)

Happy editing!