My view: a wiki by itself will not solve your problems

June 16, 2014

Every so often a sysadmin is in an environment with a documentation problem and they think 'I know what will fix this! We'll set up a wiki'. It is my view that that sysadmin is often wrong, especially if they've framed their problem that way.

There are certainly problems that a wiki can help with. If the problem is that people write documentation but then never update it because the update process is such a pain, maybe a wiki will help. If the problem is that all of the documentation that people write is scattered all over and impossible to find, sure, a wiki will provide a flexible, hopefully simple to use central place to put it all. But if your problem is that people don't write documentation, not even a quick email message to explain what they did or how to work the knobs and levers on their new widget, then I don't think the wiki will do very much because your real problem is likely to be somewhere deeper.

(There are many possible explanations for why people are not writing documentation, by the way. Perhaps they simply have not been given any time to do it. Perhaps everyone is effectively siloed, so they'd really be writing documentation only for themselves. Perhaps the culture around them has taught them that while in theory there is time for documentation, in practice writing documentation is not rewarded and doing other things is.)

System administration is unfortunately kind of prone to a kind of cargo cult approach to creating a good environment, where we deploy tools (software ones or procedural ones) in the hopes that waving these magic tokens around will produce a deep cultural change (whether we realize it or not). This approach is both naive and prone to failure. Sometimes new tools can change the culture, but equally new tools may do nothing to it and then you have the same cultural issues plus failed tools. The latter is probably much more common than the former.

This is not to say that new tools are pointless. New tools can certainly help to change culture. But 'help' is the important word here; the odds that new tools will change the culture all by themselves is much lower. And I suspect that it probably helps if you consciously plan to change the culture (using the tool as a lever), instead of not realizing that that's what is needed.

(This is partly theorizing since I have never been in a place where I drove a change of culture or consciously saw it happen, although in retrospect I think I did witness one change of culture as something between a bystander and a participant.)

I'm going to have to think about this in the future when I become enthused about the possibilities of new tools, or more specifically of introducing my co-workers to new tools. Am I solving a real problem we're having, or am I actually unconsciously hoping to drive some sort of magic cultural change into a world where my co-workers will like the idea of the kind of things the new tools do as much as I do?

(Of course if I do this right it will probably temper my enthusiasm for new tools, which is kind of a bummer.)

Written on 16 June 2014.
« The web is social, and thus minor features can matter a lot
Would I be comfortable documenting our systems in some sort of public? »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Mon Jun 16 23:59:13 2014
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.