Long ago, even before I was a high school teacher, I was a technical writer. I worked with some epidemiologists. Their job was to do epidemiology, and write reports. My job, basically, was to read reports and make sure that they said what the epidemiologists meant, to make sure the math and the English said the same thing. It was a pretty fun job.
During that time I got to read Revising Prose by Richard Lanham. It’s a hilarious and helpful little book on how to fix bad writing. (Let’s pause for a moment to appreciate the existing of a writing textbook that is fun to read, a phenomenon which is surprisingly, and worryingly, rare.) When I started this post, I planning a series on writing for developers, but then I realized that I would have to copy large parts of Lanham’s book. So instead, here’s a recommendation and a summary. But seriously, go check out this book.
I recommend Revising Prose to developers in particular because they often see what Lanham calls “the official style.” In case you can’t imagine it from the name: “in order to facilitate the processing of new batches by the accounts receivables department, methods and protocols, some of them manual and some automatic, will need to be put in place. One significant requirement of this project is that the accounting team be able to interpret the output of the reporting software…” Yikes! The official style is the insomnia-curing, bureaucratic nonsense that has you peaking at the last page number minutes after you start reading. It’s miserable. The good news is, it’s avoidable. Lanham’s book teaches the reader to take sentences like that terrifying sample and make it so that other people can read them. (And all those words for a sentence that should say: “We need automated reports that accountants can read.”)
When people can read what one another write, software development is easier. It goes faster. There are fewer meetings. There are fewer times when you blow deadlines. Richard Campbell, in a recent .NET Rocks episode, summarized a software team problem like this: “On time, on budget, built the wrong thing.” That is a serious risk. Do not build the wrong thing; do not let your team build the wrong thing. Instead, write clearly.
Lanham even gives us a numerical measure of progress, the ‘lard factor’:
You find the lard factor by dividing the difference between the number of words in the original and the revision by the number of words in the original.
In the example above, we cut 53 words (“in order to … the reporting software”) down to 8, for a lard factor of 45 / 53 = 85%. Now, that was a contrived example; your mileage may very. But Lanham does say to expect 50-67% reduction in word count. Think of the time and headache that will be saved!
Rather than spoil the whole book for you, I’m going to propose a list of what I call “writing smells.” (cf. code smells). Writing may smell if:
- It has many prepositions (of, by, from, for, about, etc.)
- It uses is and a lot (and was and may be and so on)
- All of the sentences are the same length, especially if all the sentences are long.
- It has lots of nouns that are secretly verbs.
Let me explain that last for a minute: A noun that is secretly a verb (the linguistic term is nomen actionis) is a noun that just means “the act of whatevering.” Speculation is the nomen actionis of speculate. Generation is the nomen actionis of generate. Fortunately, these nouns are fairly easy to spot in English. They often end with tion (creation, generation, migration, instantiation, propagation, etc.), and occasionally they’ll just end with ing (processing, duplicating, replicating.) If you start to see lots of these nouns, try turning one into a verb. Suddenly “to facilitate the creation of” is just “we created.”
Fixing these smells is a bit like, when writing code, you stumble on that perfect refactoring, and all of a sudden your methods have sensible names and get shorter.
So be on the lookout for those prose smells, and give that book a try. Till next week, happy learning!