The Minimum Viable Wiki

Documentation is usually considered a necessary evil. The truth is probably closer to it being necessary and evil. For most of us it's one of those things we feel we should have more of (or any at all) but never have the time. And how much documentation do we need anyway?

Most project documentation is worse than useless. Why? For the same reason that most comments in code are useless-to-dangerous - only more so. Documentation, when written, is rarely kept up-to-date. It is rarely complete. It was often never "true" to start with.

In short the docs are just not reliable

Oh, there are exceptions, of course. API docs generated from source code, for example. They will be consistent, right? Perhaps. Assuming they are kept maintained within the source. It is still possible for them to lie.

If we are Agile we don't do documentation, do we? After all the manifesto states:

Working software over comprehensive documentation

Of course it doesn't say we don't value documentation - just that we value working software more. And even then it talks about comprehensive documentation.

There is the idea of "Just Enough Documentation". I hear people talk about this and see it referred to, along with some personal interpretation. But I have yet to see a definitive write-up of this idea (please let me know if you know of one). Perhaps this is meant to be deliberately ironic? In any case, my understanding is that this relates to the sort of documents that are often seen as deliverables of a project - for example a requirements doc.

I'm not going to talk so much about those, although the principle I'll describe may often be applied. I want to concentrate on the internal, developer-oriented, documentation that describes things such as how a project is organised, what bits do what, what to expect in certain situations etc. This is often captured in a wiki that is specific to a team.

This sort of documentation is often seen as unnecessary in a Agile team. This is where face-to-face communication between team members is sufficient, isn't it?

That view seems to be borne out on projects that do have a wiki. The wiki is rarely complete or up-to-date. It quickly falls out of use altogether, or is approached with trepidation as it is as likely to mislead as inform. If it is kept up-to-date it is likely due to a Mandate From Above, which leads to more time invested in its maintenance than is worth it.

So is there a way this can be made to work? Can it ever be worth it? Why would we need it at all?

Well that first depends on your project and team. Maybe the conversations alone really are sufficient. My experience is that this reaches a limit pretty quickly. We need something. How many times have you, or someone on your team, wasted a day looking for something or going down a wrong path, only for someone else to then say, "oh, that's over here", or, "that's done differently for x reason". Yes the conversation was had - but time was already wasted

So the problem is knowing when and who to ask - especially for things you would have thought were "obvious"

In terms of the Four stages of competence this is about moving from Unconscious Incompetence (you don't know what you don't know) to Conscious Incompetence (you at least know what things you don't know). This is much more valuable than it sounds at first! If you don't know that adding a setting to a config file dumps the information you need to a log you won't spend six hours writing a whole chunk of ad-hoc logging code to do the same thing, for example. Instead you'll remember, "there was something about being able to enable logging in a config file". Now you know to ask the question and finding the answer should be quick and accurate.

Having a full specification, perhaps along with examples, of every attribute that could go in the config file might sound better. And if that config file was meant for end-user customisation you'd probably need that. But if it's some internal thing then any attempt at such documentation is likely to be incomplete and/ or out of date - if written at all

But a line that says, "logging is configurable", somewhere that people will read leaves out those noisy, unstable, details and simply informs you of what is possible. You now know what you don't know (i.e. how to enable logging), whereas before you didn't even know it was possible. Details can be asked for.

So my recommendation for maintaining team information on a wiki is to stick to the briefest possible comment that moves the reader from Unconscious to Conscious Incompetence. Unless you really need it avoid the level of detail that will leave it unmaintained and incomplete.