Musings on technical writing
I'm a simple soul, amused by simple things.1 An extract from Sam Leith's "You Talkin' to me?" being a good example.
"Some historical simplification has been necessary for reasons of space."
The life of a writer...
... buried deep within an IBM laboratory, working on strictly non-fictional material, was one that suited me perfectly well for, erm, a working lifetime. I agree it may not have been highly-paid (no "may" about it). And it may have lacked the excitement, say, of a foreign correspondent (too much travel) or a gossip columnist (too many horrible people) or a lobby correspondent (far too many horrible people). But I enjoyed describing how to wrangle a variety of computing systems. And when affordable personal DTP and word processing systems became available for use at home my quotient of childish glee rose further.
As did some of my freelance earnings.
It's sadly true...
... that, in general, technical documentation sometimes leaves a great deal to be desired. Consider the view expressed by Robert "Zen and the Art of Motorcycle Maintenance" Persig, from an interview conducted by Hugh Hefner's daughter in the late 1970s in a magazine called "Oui":
PIRSIG: Technical writing is a good example, because it's the dullest, most boring kind of writing. Yet I found that within tech writing on digital-computer hardware — electronic circuits and the ways in which they're
arranged — the range for quality was enormous. The writing I did for those computer manuals was some of the most gratifying work I've ever done.
OUI: But still not as gratifying as writing Zen and coming up with a best seller, right?
PIRSIG: In both cases, the options for quality are infinite. In mathematics, however, there are orders of infinity: infinities that are infinities of infinities. So I preferred to write Zen, because of the higher order of
infinity. But in each case, you can have a good time. One technical manual that I wrote actually caused an engineer to break into tears when he read it. He'd designed this thing and felt it hadn't been appreciated properly. When he saw my
manual, he knew that I understood its worth, and it pleased him so much he burst into tears.
(The interview's neat accompanying illustration went uncredited.)
I concede the possibility...
... that some of my own writing has, on occasion, reduced some of my readers to tears. But I suspect they would have been of frustration or rage. There remain opportunities to sneak in either, or both, humour and elegance and I took them when I felt I could get away with it. Never underestimate the power of a well-placed footnote in that regard.
Erwin Schrödinger's elegant 1943 essay "What is Life?" has one that took me straight back over 30 years to the concept of a VSAM disk file's Control Interval and ways for CICS transactions to permit multiple users to write, or even just read, other records in the same CI safely, and without locking up the system unnecessarily. Not a concept that I have to think about much2 these days, but such things mattered a great deal in the online transaction processing systems of the time. (And probably still do.)
I used just such a footnote in 1984 in the CICS Primer. It neatly enabled me to side-step the several pages of technical explanations (and, sometimes, ill-informed or merely contradictory opinions) I had been sent by a variety of more senior technical folk that would otherwise have been necessary. "Eschew obfuscation", say I.
Or a (M)ounce of simplification can be worth a tonne of explication.