Reading old manuals
Over the holidays I bought a box of old computer manuals at a flea market, mostly for the binders. Under the binders was a reference manual for a dot-matrix printer, printed some time in the mid eighties, two hundred pages, spiral bound. I have read most of it now, which is more than the printer's original owner did, judging by how stiff the spine was.
It is a good piece of writing, and I have been trying to work out why.
The first thing is that it assumes nothing and wastes nothing. Chapter one tells you how to take the printer out of the box and which bits of cardboard to keep. Chapter two explains, in about a page, what a control code is, and then shows you one. By chapter four you are sending escape sequences to change the line spacing, and you understand what you are doing, because every step was built on the one before it. There is no point at which the manual says something is simple. It just makes it simple.
The second thing is that it tells you what will go wrong. Every section ends with a short list headed, plainly, If it does not work
. Paper feeds crooked: check this lever. Characters come out garbled: you probably sent the code for the other character set, and here is how to tell. Somebody had clearly sat at a desk with a phone and a list of real complaints and written them down.
Compare that with the documentation I read most days. It tends to be a reference with no guide, or a guide with no reference, and it is almost never honest about failure. The happy path is described in detail; the moment something goes sideways you are on your own with a search engine and a forum thread from four years ago. I do not think the people who write it are worse writers. I think nobody asks them to write the failure section, and nobody budgets the time.
The third thing is the index. Thirty pages of it, cross-referenced, with entries for the words a confused person would actually look up rather than the official names. Smudging
sends you to the ribbon. Noise
sends you to the quiet mode. Whoever compiled it understood that an index is a list of questions, not a list of headings.
I have started stealing from it. The internal notes I write now end with a short section of things that will probably go wrong and what they look like when they do. I keep a list of the words people use when they ask me about a system, and make sure those words appear somewhere in the text. It is slow, and a little humbling, because it means admitting in writing that the thing I built can fail in ordinary ways.
The printer itself is long gone, of course. I have no idea where it ended up. The manual is on my shelf next to the good dictionary, and I expect it to stay there.