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.
Well, one way of looking at it is the fact that while conversational language is constantly changing, formal language is much more resistant to said change. If everyone writes the way they speak, how can you gauge things like grammar? Suddenly, without the rigid rules, the people who don’t speak English (or whatever language) as their mother tongue (or at least who didn’t learn it early in life) are at a grave disadvantage not only in writing, but in reading as well.
You have to settle on standards. It’s easier to teach language learners the formal, structured language and have them pick things up from the masses. I assure you I can find things written in conversational English from the UK that you wouldn’t really understand. You’d have to work to get the gist of it. If you don’t have standards you can’t draw the line. How can you tell people to write conversationally when that would result in the document losing its clarity to a larger number of readers.
Sure, I understand both sides of the argument, but I think conversational writing is appropriate for subjects for which many (or at least several other) resources already exist, or for documents that are meant to be informal. Other than that, best to stick to the standards…
Good arguments. I should point out for the record that Martin Fowler is, in fact, British.
There’s a difference between writing conversationally and using slang, though. I don’t think metaphor has much of a place in technical writing, but conversational language sure does.
Any translator worth her salt should be able to deal with conversational language… But technical documents aren’t usually translated right away, if ever.
I completely agree with your points, Skrud. I think good writing skills are very important in software writing, for the sake of documentation. And I think that conversational writing is preferable to formal writing, and like everything else in life, is good only when it comes “in appropriate quantity”. Meaning, find the balance between being informative and being readable.
I would also like to comment that I think you have a very good writing, telling from your blog posts. I think it’s an excellent idea to maintain a blog, because it does exactly that – sharpens your writing and communication skills. It makes you practice writing.
I should start a blog too to become competent in writing as well. :)
I think the quality of writing has become abyssmal in several places: Many forums, chat rooms, some textbooks, and probably at times academia (too much jargon to make one’s self look important).
I’ve noticed that the better I understand something, the better I can express it clearly and concisely. If I can explain to you something in two sentences instead of a page, that is obviously much easier to understand. If I take a page to explain myself, it’s because I’m really not 100% sure what to say and how to express it.
Authors who write so horribly should: 1) Learn english, not engrish 2) Understand intimiately what they want to say 3) Reflect on how to say it.
Of course, I know I make it sound simple, but it really isn’t. However, I think that using a content/length ratio is a very good first start.
Great article.