Wandering Thoughts archives


Documentation is not free

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.)

sysadmin/DocumentationIsNotFree written at 23:46:33; Add Comment

Page tools: See As Normal.
Login: Password:
Atom Syndication: Recent Pages, Recent Comments.

This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.