Technical Writing
Posted by Skrud at Tuesday, May 2nd 2006 at 5:20pm
Bad writing is a pet peeve of mine, particularly if it’s excessively prevalent in something I have to read. I’m not talking about improper grammar or spelling mistakes – those annoy me, too, but to a lesser extent. I’m talking about bad writing.
A lot of technical documents are badly written. This has nothing to do with the technical competence of their authors, but a lack of elegance with the English language. Some of the greatest minds in Software Engineering aren’t some of the greatest writers, which is no great surprise. Yet still they have to publish papers about their research, and then I have to read them while studying for my exams.
I know I’m not the only one who feels this way. Joel Spolsky has even gone so far as to compile a book: The Best Software Writing I which is a collection of well-written articles about software. To quote his blog:
The software development world desperately needs better writing. If I have to read another 2000 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!
I think there are two scales that you can analyze a particular technical document on (and this may extend to other kinds of documents, but I don’t know about those): How easy is it to read? And how easily can you extract information from it? There were about four things I had to read in studying for my Software Architecture course, and they each fall into different places in the spectrum. However, I don’t think an article can be easy to extract information from if it isn’t easy to read first.
Formal Language
Formal language is silly. In formal language the writer attempts to avoid any identifying remarks. The writer completely removes himself emotionally from the document. The writer does not use contractions and writes in the third person. When one is writing in formal language, one does not infer gender on any third-person singular pronoun. Instead, one must awkwardly use the gender-neutral “one” and refer to themselves, if they must, as “the writer”.
Here’s the thing about formal language: your brain doesn’t care. It’s much more difficult to retain knowledge from something written formally as oppose to conversationally. Formal language reads as if it were written for robots, not for humans. I suppose there is an assumption that when you’re writing a technical document, that your target audience includes technical people. All too often authors focus on the technical but forget the people. Regardless of the education level of your target audience, no matter who they are, they are people. Whenever you’re writing something, I think it’s fair to assume that it’s going to be read by a person, and not by a machine. So why not write something that you think a person would be able to read?
Kathy Sierra has tons of stuff promoting the use of conversational language over formal language. Here’s a tidbit from Creating Passionate Users:
When you lecture or write using conversational language, your user’s brain thinks it’s in a REAL conversation!
In other words, if you use conversational language, the listener/reader’s brain still thinks it has to hold up its end, so it pays more attention. It really is that simple, and that powerful (at least if you really want to help users pay attention and remember your message).
I for one believe that it’s much more important to get your message across clearly than it is to sound like a pompous, professional ass. There’s no point in writing something that no one is going to understand. In fact, I suspect that an overuse of formal language may be trying to cover up a lack of understanding on the author’s part. Since it’s much more difficult to parse “formal” documents, it’s tougher to pinpoint inaccuracies in the arguments.
Philippe Kruchten’s paper on the 4+1 View Model of Architecture is a great example of a paper that uses formal language way too much. The phrase structure is awkward at best, and I had to read each tedious paragraph repeatedly to get anything out of it. The paper was, however, chock full of useful information.
Counterpoint
Conversational language can be a great help in terms of being easy to read. Unfortunately, that’s not the only thing needed in a technical document. Ultimately, the document exists to disseminate information, not to entertain you. That’s no excuse to write tediously and formally, but it is an excuse to pay attention to how well your writing presents information.
We had to read Patterns of Enterprise Application Architecture by Martin Fowler. I think this book is a great example of something that’s very easy to read, yet at the same time is difficult to extract information from. Fowler writes very well. He writes conversationally, as if he’s talking to you and telling you about common problems in Enterprise software architecture over a pint of Guiness. The problem is that I didn’t find the book to be very well structured. It would be very easy to read, but there also seemed to be a lot that was simply glossed over. In one sentence, Fowler may make an abstract reference to something incredibly important and then never return to that topic again. He might say something like “if you use a Data Mapper then Lazy Initalization is not enough, and you must use a Proxy” – but he never says why. (It took me until literally the day before the exam to understand this, when really he could have summed it up in a sentence or two).
Conclusions
It’s very difficult to find a balance between clear, concise writing and detailed technical writing. One the one hand, you sound like an android – or worse, pretentious. On the other, you can easily let valuable information slip through the cracks in your writing, and your technical document becomes no more useful than celebrity gossip. You need to experiment in order to try and find the right level of abstraction for your writing. It’s not at all different from experimenting to find the right level of abstraction in your object-oriented software. With time, (I hope) it’ll become second nature.
Editing can go a long way. I think technical papers should get reviewed not only by other technical people, but also by writers. Someone who isn’t necessarily familiar with the technical field surrounding the paper’s context, but is a language expert capable of pointing out awkward written constructs and making the paper readable by humans. I for one would love to read software architecture documents as naturally as my RSS feeds.
Caveat Emptor
I’m in no way an “expert writer”. I have little experience in my academic career reading technical documents, and I have minimal experience writing. All I know is what kind of writing I find helps further _my_ understanding. These are only my opinions, so take everything I say with a grain of salt.
