My obsession with documentation has started to take a somewhat
unsettling turn. It is making me ignorant. Let me explain.
Almost all of my reading is non-fiction at best, tends to be
technical. Lately, as I read, from deep inside I hear a voice saying::
"I refuse to understand this. What the author is describing
would be explained at a glance with the proper diagram. Since
there's no diagram, I'll cover my ears and chant 'la la la'
loudly. So there"
Case in point; the instructions for taking care of the hole in my jaw left by my recent tooth extractions. The handout described what to do and for how long, covering about 10 days. Where's the timeline? As I read I have to mentally create an image of taking ibuprofen, rinsing with salt and baking soda, not eating nuts, flushing with the little syringe thingy ... then visualize the next 10 days, associating each event with a range of days. Come on! If *you* took the effort to make that timeline, all the readers of the pamphlet would be spared.
Some things, like Zope's component architecture are even more
complicated than care of ex-teeth, don't get me started.
Nothing however, is more inscrutable than the workings of our pressure tank. Because it's filled by an old jack pump, it must be bladderless. A float-operated, adjustable air valve controls when air is released from the tank. It defies *all* comprehension.