Why writing documentation is no fun

September 3, 2006

I recently had an insight about why so many sysadmins (and programmers) would rather have a root canal than write documentation for any length of time. (While some of these feelings can be blamed on people feeling unskilled, not all of them can. Certainly I can't claim with a straight face to be completely unskilled, and the idea of having to write documentation for any length of time still makes me gloomy.)

I think it's because documentation doesn't do anything on its own, leading to a lack of feedback on your work.

Us sysadmins and programmers are used to doing things where we get immediate feedback. When you build a system or write code, you can see your work actually doing things, right then and there. (Sometimes what you'll see is your work blowing up, but you are still getting feedback.)

But when you write documentation it just sits there until someone else reads it. (And you can't really do anything with incomplete documentation, unlike incomplete code or systems, where you can at least exercise what you have.)

So, in short: seeing your stuff doing things is fun. Look, you did that, isn't it neat? Documentation doesn't do things; it just sits there, with none of the usual fun to be seen.

Plus, there's another aspect of this: sysadmins and programmers work in an environment of fast feedback, so I think we get habituated to feel that getting that feedback means you are working productively, and not getting that feedback means that something is wrong. So writing documentation means you're not getting that feedback, which means that something in the back of your mind feels that you're not getting things done, even if you're turning out the words.

(Matters become even more demotivational if your co-workers don't give you much feedback; there is the pernicious feeling that what you've worked on is clearly valueless. No one likes to work on valueless things, even if they are technically well executed.)

Written on 03 September 2006.
« Weekly spam summary on September 2nd, 2006
A thought about interactive development environments »

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

Last modified: Sun Sep 3 22:18:38 2006
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.