Documentation is not free

August 27, 2006

Yes, system administrators should document things. At the same time, it's important to understand that documentation is not free; it has a cost. Since documentation does not appear from thin air in zero time, producing it costs people's time.

(And this doesn't even count testing it afterward.)

Unless your sysadmins don't have enough to do (which is a rather rare occurrence around here), this means that documentation costs real dollars. If you want to do everything you currently do plus documenting things, you need more time, which means that you need more people, which means more money. If you hold money constant and still demand documentation, you will get less other things done; the time has to come from somewhere.

(Please don't try to force your sysadmins to work extra time for nothing. This rarely works well.)

Thus, if you want documentation you need to explicitly budget for it, one way or another. If you don't, you're unlikely to get any documentation until people run out of other things to do.

(A corollary is that you can measure the real importance of documentation to an organization by how much they budget for it.)

If you really want documentation, you also need to defend it during crunches. It's a very tempting target for schedule cuts, since nothing breaks without it (at least in the short term) and it's usually cleanup work, done after systems are working.

(Another way to put this is that the costs of no documentation are usually a lot less obvious than the costs of unbuilt systems.)

Written on 27 August 2006.
« Weekly spam summary on August 26th, 2006
Documentation should be cheap »

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

Last modified: Sun Aug 27 23:46:33 2006
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.