Sunday, 19 November 2000
.....
Do not write so that you can be understood, but so that you cannot be misunderstood. -- Quintilian
One of my favorite books is also one of my favorite technical books: Smalltalk-80: The langauge and its implementation. Comprehensive, lucid, well-made, and beautifully laid out, it's a delightful experience even if you aren't particularly interested in doing any Smalltalk programming. Really good technical writing has virtues beyond the nit-picky documentation of some particular system. Much of the technical writing I find admirable manages to usefully focus on concrete detail while stimulating a broader understanding. Indeed, I am especially tickled when a broader understanding is produced through concrete details (and vice versa). Such writings have a very high quotient of "Aha! Oh cool!" moments.
Alas, the technical book shelves sag under the hordes of titles promising mastery of eJava for iBusiness in 24 dummied hours of XML enabled web development -- in Plain English, no less. Frankly, I'm sure you can get higher quality, more absorbent, softer toilet paper for less than $49.95 a shot...though, whatever the pain of using these tomes at the toilet, it is probably less painful than reading them, or, worse, relying on them for techncial information.
Ok, that was a cheap and easy shot, but if a self-published article on the web is not the proper home of cheap shots, what is? At least, I didn't "take on" self-published technical articles on the web!
It's interesting that the now classic example of good technical documentation -- the O'Reilly "animal" books -- really isn't all that good an example of technical writing. The animal books are cleanly designed, visually comfortable, and often quite useful, but their relentless consistency is a symptom of their failure to be much more than reference works and tutorials. Even the titles are formulaic: "Foo in a Nutshell", "Windows-Something Annoyances", "Blarghing, the definitive guide". When done well, the animal books are fine manuals but, in the end, they are as constrained as, if way more classy than, the For Dummies... books.
I will not talk about those abominations.
One interesting aspect of technical writing is its many forms: from newsgroup and mailing list postings through notes, how-tos, articles, books, and finally, perhaps largest in scope, to Knuth's Art of Computer Programming. Formality provides several axes of variance as well. And while "needed prerequisites" does help sort technical works, I'm not as sanguine about the "beginner/intermediate/expert" labelings. For example, I am by no means an expert programmer -- that is, I lack expert programming ability -- but I have enough familiarity with the concepts, terminology, and conventions of the field to be able to happily read many "for experts" texts. Of course, it does seem to make sense to distinguish between introductory topics and texts and advanced ones, but this division seems to have a different flavor.
I've done a fair bit of newsgroup and mailing list technical writing but have recently started experimenting with slightly longer and less ad hoc forms. And it's painful, very, very painful. Which is why I'm writing this article instead of those.
I am finding that one kind of good technical article has much of the feel of one kind of good philosophy paper, which is, I suppose, why I like it. I'm thinking of the sort that where, as you read it, you don't puzzle out what the author's saying, but rather the presentation and your thinking about it merge. Of course, this sometimes mean that it's damn hard to figure out what's wrong with the argument.
Introductory writing is much harder, I find, both in matters philosophical and matters technical, especially when you have a deep fondness for the richness and subtlety of a particular topic. I find myself so pained by the need to simplify, to distort, to misrepresent so often by mere omission that I prefer not to write at all, but to go back to reading. It is much easier to admire the fruits of another's sweat than to labor oneself. But, unlike in other areas, the idle doings of the intellectual leisure class are rarely accompanied by the economic, social, emotional, and even intellectual consequences that make for the well-lived life. To be a parasite of this sort can be pleasurable and variably satisfying, but it it seems to lack closure.
Publication, fame, and fortune are not the point. Even the armchair intellectual feels the difference between the daydreamed fantasy and solid, crafted work. And, done right, with spirit and kindness, we can make out of this too often dry and dreary landscape of acronym, buzzword, and jargon-laden gibberish a library worth keeping for its own sake.
(If you have a favorite bit of tech writing, please write up a testimonial and send it along to me. I love discovering new gems. Oh, yeah, if anyone can track down the Quintilian quote, talk to me!)
See also Finishing School <http://monkeyfist.com/articles/700>
This is Technically Writing <http://monkeyfist.com/articles/720>