(absolutely quite a bit, actually, say it again)
James at work said yesterday that often he finds, paradoxically, the code that is best documented is also the code that needs documentation the least, since it tends to be well designed and written in the first place.
I know what he meant, and it rang a little bell with me (although whether my code falls into that category is for others to judge :) ).
In lots of the places I’ve worked I’ve tended to be one of the few people who writes documentation, and I often wonder whether anyone else reads it. Is it, perhaps, all a monumental waste of time?
That said (and when I’m not having a bad day), I believe that to worry too much about whether it gets used would be to miss the fundamental point.
The reasons that I write documentation, in order of importance, are:
- to clarify what I’m trying to do
- to clarify why I’m trying to do it
- to offer up my design for peer review
- to explain my implementation choices
- to note avenues that I’ve tried and rejected, to avoid others doing the same
- to help other people use what I’ve done
If anything, the “why?” is even more important that the “what?”. Spend a bit of thought on that one, and the rest may turn out to be irrelevant.
In any case, having other people use the documentation as a reference comes pretty far down the list of priorities.
Which doesn’t mean that I don’t want people to do that (it would really help, frankly, if more people would RTFM!). It does mean though that I’m not going to lose too much sleep if I feel that I’m the only one reading what I write.
At the end of the day, writing documentation, for me, is an essential part of the process of writing software, especially when working with others. How can you code a system that you can’t describe in words or pictures?
Having other people read it is just a bonus.