Writing influences

I was recently asked who my main influences in technical writing are. It’s an interesting question, because there is so much bad tech-writing out there. I’m a coder, but I also like to write (perhaps “like” is a strong word — the writing process itself sucks, being full of turmoil and internal desperation to get things out and correct, but I love the result).

John McPhee is a good start. His Annals of the Former World (four books written over twenty years, each taking a look at the geology of a different section of the US at about the same lattitude, from east to west) is amazing. His language is uncomplicated and clear, often funny, and there’s little fat.

I’m going to (shock) plonk Annie Dillard in the same bucket as Neal Stephenson. Both are highly descriptive, and have a certain violence with language that is entertaining. I read Dillard’s Pilgrim at Tinker Creek in 1979, and it was a revelation that you could do things like that with english. So was Stephenson’s Zodiac, which isn’t technical writing (and has a weak ending) but is a lot of fun.

[Rule #2: Make reading fun! If someone isn’t thinking about chuckling or saying, “Ooooo” from time to time when they’re reading documentation or code, you’re not going to hold their attention, they’re not going to remember what it was they read, and your chance for pushing understanding-that-sticks at them will have been lost.]

Henry S.F. Cooper is the unsung hero of the aerospace essay. He’s been writing about the space program since Apollo landed on the moon. For me, his most gripping stuff is in The Evening Star, where he describes how engineers debugged a race condition in the operating system of the Magellan probe, orbiting Venus at the time.

Early-on, I loved Kernighan and Plauger’s Software Tools, which is a good walk-through of some baby programs and design philosophy. I had an advisor/mentor in college who helped me a lot with my technical prose, ripping it to shreds when I thought I had it perfect, and making me write draft after draft before I touched code. K&P are like that — highly crafted and exact, probably too crafted to be enjoyable reading, but accurate and lean and business-like, like a greyhound doing its job.

I’ve left folks out. ACM published some “distinguished doctoral dissertations” in the mid-80s that were a lot of fun (e.g., Katevenis’ thesis on RISCs, and Ungar’s work on a high-performance version of Smalltalk). Donald Knuth’s TeX work is great (and the cartoons by Duane Bibbey help a lot, see rule #2). Literate Programming is an interesting idea, but it’s also very hard to do a decent job of it (your average programmer is hard-pressed even to make sensible doc-comments). Elliot Organick wrote some depressingly boring (the “please God kill me now” kind of boring) books on Multics and the iAPX 432 Intel processor of the early 80s — I use his works as what to avoid, even if he was a hero for having tackled tough subjects like operating system internals.

[Rule#1: Ship out drafts anyway. This is a corrollary to the grit-your-teeth reality of the “Crappy First Draft” attitude. Just get it done, then revise the dickens out of it. If it’s an internal document, ship it out for feedback even when it’s not bloody perfect. The the most disturbing thing — other than a crushing total rewrite — is when a Crappy First Draft comes back with no comments, or “Boy, that was great!”]

This entry was posted in Uncategorized. Bookmark the permalink.