Quality Ingredients: Story, Voice, and Metaphor
I’ve been thinking a lot about writing lately. There’s been a practical reason — I’ve written an ebook version of Rubyisms on Rails that I’ll tell you more about later — but my motivations are more abstract. I’ve been reading way too many technical books lately. Many have been good, but as one afternoon browsing the bookshelves will demonstrate, most are terrible. As Joel Spolsky exclaims in exasperation in the forward to the excellent book of software essays The Best Software Writing 1:
The software development world desperately needs better writing. If I have to read another 200-page book about some class library written by 16 separate people in broken ESL, I’m going to flip out. If I see another hardback book about object-oriented models written with dense faux-academic pretentiousness, I’m not going to shelve it any more in the Fog Creek library: it’s going right in the recycle bin. If I have to read another spirited attack on Microsoft’s buggy code by an enthusiastic nine-year-old Trekkie on Slashdot, I might just poke my eyes out with a sharpened pencil. Stop it, stop it, stop it!
For Spolsky, the most important ingredient missing from dull technical books is story. As he puts it, good tech writing captures your interest by creating a plausible or interesting story. The resulting text may be much more verbose — in an example, he spins out the insipid truism “a good team leader provides inspiration by setting a good example” into an involved 400 word story — but the story is what makes you want to keep reading more. Looking at some recent purchases, I can see the effectiveness in some notable recent books. In the simplest case, you can go far with a compelling example application you elaborate in each successive chapter like Enterprise Integration with Ruby does.
is built on the solid story of an example integrated in each chapter. It’s not necessary to have one big story, however. You can also structure your book as a sequence of independent smaller stories, as recent favorites Practices of an Agile Developer and The Art of Project Management did so well.
On a contrasting note, Amy Hoy in an article disparaging the suggestion that being a woman is what solely makes her a good writer, suggests another important ingredient is
breasts voice. The way to make a technical article compelling is to make it personable. This is something that Joel hints at with his dig at “16 separate writers” and it is something certainly borne out by the selections in the book — practically every selection is a blog posting and is thus opionated, direct, and personal by their very nature — but Joel focuses more on what is being said than how it is said. Voice matters, and nobody has done as good a job asserting the importance of a personal tone than Amy has. But it’s hard for technical writers to understand. When we are first learning to write essays in elementary school, we’re taught to prize dispassionate objectivity above a personal voice. This is not to blame teachers; that makes a lot of sense when you’re teaching writing to fifth graders whose idea of an argument might run along the lines of “This book is bad because I didn’t like it,” and good writers learn eventually to balance their personal opinions and objective fact in essays. Unfortunately, nerds usually aren’t good writers, and I think too many books are written by developers too mortified to express their personalities (even if they could). But if you edit out your personality from your writing, you might as well do your readers a favor and delete the whole book. An example of books that benefit from voice are Martin Fowler’s classic Refactoring and the more recent book Refactoring Databases. Refactoring code is a discussion prone to tedium, but the books succeed because they sparkle with clarity and reflect the single voices of their authors.
Before I continue, I should clarify a few points. Joel’s emphasis on story and Amy’s on voice are not mutually exclusive: I can explicitly emphasize that something happened to me or something happened to me, but both voice and story exist in any compelling technical narrative. The second point is you can only do so much.
There will be always be some dullness that’s unavoidable in technical literature. It’s simply impossible to make some content interesting (ever read a truly fun man page ever?), and if you tried to make it fun, you’ll actually annoy your readers (“Hey kids! Let’s sing the arguments to GCC as a song!”). But a technical book is more than a listing of compiler options or valid function parameter or working code samples. Like introns in DNA, the bulk of any technical work is interstitial material that holds the boring stuff together. And that is where your writing should shine.
Which brings me to my point. I want to draw attention to another important ingredient that complements those two yet gets short shrift: metaphor. To see what I mean by metaphor in action, look at my DNA example from the previous paragraph (I know, technically it’s a simile). Assuming you knew what an intron is — in a book I obviously would explain it more explicitly than a blog post — that aside conjures up a rich web of allusion that clarifies the emphasis of the point (that the bulk of your book might not be technically explicit and yet still be meaningful for the whole). The beauty of metaphors is they evoke all sorts of mental associations in your readers that act like scaffolding (a metaphor) that helps your readers learn material by building upon concepts they’re innately familiar with. And they come with an expressive power that allow you to express complicated ideas succinctly through allusion (ie, instead of having to spell out what scaffolding is used for like I just did, you can just describe it as scaffolding and leave the reader’s brain to fill in the rest).
Metaphors are truly useful things, and since this is my soapbox (another metaphor!), I’ll declare that metaphors are woefully under-utilized in technical writing. I think one reason for this is technical writers are discouraged from metaphor to be more universal — if I make a metaphor specific to New York City, it might fall flat to a reader in Germany or India; not only would I have to explain my technical content, I’d have to explain my metaphor! You can avoid regionalism pretty easily though, so I think the biggest stumbling block is geeks themselves. Mainly, that same literal geek writer that sticks to the facts and recoils in horror from anything that smacks of poetry.
This is a dearth made more unfortunate because good metaphors reinforce both story and voice. If you are boring like me and have no personal experiences to relate, you can fabricate your narrative on the back of a metaphor instead. And your use of metaphor breaks your text out of the dry and technical and provides a place for your unique personal voice to be expressed.
To give an example of this in action, I recently had to explain the virtue of iterators in Ruby for the ebook on Rubyisms. I could describe how they work technically easy enough, but I felt that a metaphor was the best way to explain why iterators make more sense (and given the number of programmers still iterating through array elements in Java, this is something most programmers still don’t understand). So I brought out an unlikely metaphor to anchor why iterators are better: traveling crosscountry on local roads vs. highways.
Iâ€™ve described this book as a drive down local roads, but now itâ€™s time to take to the highways. Highways are fascinating concepts. Although they seem like an inevitable part of the driving infrastructure, highways are actually quite new in the history of roads. As recently as the early 1900s for instance, a drive across the country was essentially the same as driving across town, navigating a dense network of local roads that would get you there eventually but not efficiently. Routes were not clearly demarcated, and road maps as we know them didnâ€™t exist. Each driver would have to figure out their own routes, a challenge when navigation comprised only instructions like â€œtake right at third fork in the roadâ€? or â€œturn left at the willow tree.â€? Of course, getting lost was inevitable. And accidents and mishaps were all too common on neglected backcountry roads. This might seem a cartoonish depiction of long-distance driving, but itâ€™s thatâ€™s largely a reflection on just how fast, safe, predictable, and even boring intercity travel has become due to highways. And thatâ€™s because the highway changed the very nature of long-distance trips.
Highways are built not from asphalt and cement, but from limitations. Instead of connecting to every road, a highway runs largely isolated from local roads with only a scant selection of exits where new traffic can enter and leave. Highways never actually intersect directly with other roads except by exits and ramps, meaning traffic control mechanisms like rotaries and stop lights arenâ€™t needed and traffic can move faster. This also has the additional effect of discouraging local traffic from taking the road, leaving the road for the serious long-haul motorists. Most significantly of all, highways simplify navigation. Rather than picking a route over local roads, the highway is a road that limits your route. To enter a highways is to largely surrender navigational choices: there are no turns or forks in the road to decide among; backtracking and U-turns are forbidden; your only option is to drive forward until you reach your exit. You can drive faster because you have less to decide, and you can navigate easier because you have less to consider. And so a trip from New York to Chicago used to be an impossible slog of endless directions. Now, itâ€™s a largely mundane trip of only 3 highway segments (although admittedly, you stay on I-80 for an astonishing 750 miles of the way).
I then go on to explain that running through array elements by incrementing an integer index is a lot like driving cross country on local roads, prone to complexity, mishap and error. From there, an Iterator is a lot like a highway, less worrying about navigation, more involvement with the act of driving. I’m not posting this example to toot my horn in any way (and not as a teaser for the book, although it works that way). It’s just a nice recent case where I pulled a metaphor out of my writer’s toolbox.
From there, I was able to spin out the explicit technical reasons why it’s better to use iterators, but I feel I can succeed because the reader is able to relate to the scaffolding of highway driving, a metaphor well understood by much of my audience (sorry to readers in deepest Papua-New Guinea). I think you’ll agree it’s a lot more vivid to think of access violations as wrong turns and fencepost errors as navigational errors. You can’t help but learn the material because you already know it in some sense. Metaphors aren’t poetic navel-gazing, they’re a necessary ingredient to the book. So, mix them in sometime. I think you’ll like the taste.
Update: The book is coming out soon. I’ll post details when I know. Watch for an announcement soon. I promise!