An illustration of one reason that documentation is hard

February 7, 2009

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:

From at 2009-02-07 05:56:08:

On a related note: it is worthwhile to emphasize that wikis, blogs, HOWTOs, et cetera, are not documentation.

(It is actually quite embarrassing for an experienced sysadmin to sometimes "rely on Google", so to speak, because particularly Linux remains to be more or less completely undocumented.)

- j.

From at 2009-02-08 01:39:59:

@misguided commentor above me

I'm afraid that I've got to disagree with a couple of your ideas. First, the idea that HOWTOs are not documentation. That's such a silly idea that I haven't been able to even figure out why you would think that. I'd grant you that wikis might not always contain documentation, but I think your post would have been mch more correct if you had said "not necessarily documentation".

Since the part about Linux being undocumented was flamebait, let's skip that and move straight to the part where people (admins, specifically) shouldn't rely on google. I've got to admit, I'm really curious about where you work, if you have every conceivable trouble condition for your machines documented into your internal knowledgebase (does that count as documentation? I don't think I've heard your description. Anything you can swat a fly with?).

Please reply. I would like to hear more about your documentation and who produces it.

Matt Simmons

From at 2009-02-08 04:17:31:

Here goes a reply from this "misguided" individual. (Oh, how that term reminds me of "false consciousness" from the 1970s ;-).)

I agree that perhaps a better wording would have been that HOWTOs etc. are "not necessarily documentation". And I do not work in a wonderland in which "every conceivable trouble condition" is documented. But I do work in environment in which jumping to Google is generally discouraged as the last option. I also work in a place where we tend to examine the source code in case of problems. Against this you can probably already understand that chitchat in blogs is not exactly the kind of information we are after when having problems with the systems we administer. (And related to this, there was no "flamebait" in the post.)

Perhaps I was talking about system documentation too broadly in a context specifically related to system administration. I was more after specifications and documentation about system interfaces when making the observation related more to reliability and validity of documentation, the two factors that in my humble opinion defines the essential properties of (system) documentation. And yes, there are systems for which that kind of documentation is provided by the vendor.

Perhaps this suffices as an closing analogy: you do not rely on Wikipedia for academic work.

- j.

From at 2009-02-10 07:19:41:

While this is not necessarily related to system administrations, I have noticed that documenting a system greatly facilitates changing it, thus invalidating the documentation. I have some remarkably complete documentation of the internals of our product, written 14 years ago as part of a project that completely rewrote those internals. Ideally one keeps documentation up to date, but frequently this kind of thing is what happens.

Written on 07 February 2009.
« Our SunFire X2100 nVidia Ethernet experiences
When bash sources your .bashrc »

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

Last modified: Sat Feb 7 00:33:35 2009
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.