An illustration of one reason that documentation is hard
My need to write an entry on how to force the outgoing interface on Linux handily illustrates the problem of writing documentation when one is too close to the problem (and hence the need to test documentation).
At the time of the original entry, it was probably obvious to me that you had to combine the firewall marking approach with SNAT, so I didn't bother explaining this explicitly. Indeed, reading carefully I can see that I more or less said that in the entry, although not clearly enough for me to see it later when I reread the entry because I needed to solve the same problem again.
(A certain number of WanderingThoughts entries are in large part notes to myself for future use.)
This is a difficult problem, since it's not just an issue of adding more details and being more explicit. Not only do you wind up belabouring the obvious sooner or later, but writing is not free, so more details means less writing elsewhere; you have to draw the line somewhere. (Plus, writing out what you feel to be painfully obvious is not fun at all.)
The thing that this makes me especially twitchy about is lab notebooks. Unlike other documentation they're written more or less explicitly for yourself and never tested on other people, and I tend to write them in a fairly terse style where I wind up assuming great deal of context (partly because one goal, at least for me, is to write them fast so that I will write them at all). Rereading some of my notes after the fact has been a little bit alarming, and I've recently found myself consciously backing up to add more details and context to something 'obvious' that I scribbled down.
Comments on this page:Written on 07 February 2009.