Good technical writing is not characterless and bland

February 11, 2015

Recently Evan Root left a comment on my entry on a bad Linux kernel message where he said:

I believe the reason why the Yama message is cryptic and 'intriguing' is because tedious committee sanitized messages such as "AppArmor: AppArmor initialized" are at odds with the core principal behind Ubuntu "Linux for human beings"

This is not an uncommon view in some quarters but as it happens I disagree with it. It's my view that there are two things wrong here.

The largest is that clear technical writing doesn't have to be characterless. Good technical writing is alive; it has personality and character. Bland dry technical writing, the kind of writing that has been scrubbed clean of all trace of character or voice by some anodyne committee, is not good writing. You can be informative without boring people to sleep, even in messages like this. In fact, if you look around it's plain that the best technical writing does very much have a voice and is actively talking to you in that voice.

(There is technical writing where you mostly have to scrub the voice out, like technical specifications, but this is because they are very formal and have to be absolutely clear and unambiguous.)

Such writing with personality is of course harder to create than bland dry writing, which is one reason people settle for unobjectionably bland writing. Pretty much anyone can turn that out on demand just by being as boring and literal as possible. But that is not what people should be producing; we should be producing writing that is clear, informative, and has a voice, even if it takes more effort. This is possible.

(This is the same broad school of writing that produces useless code comments that say nothing at great length.)

The smaller thing wrong is that the original message of 'Yama: becoming mindful' cannot be described as a message for human beings (not in the sense that the Ubuntu slogan means it, at least). That is because it is an in-joke and practically by definition in-jokes are not particularly aimed at outsiders. Here the audience for the in-joke is not even 'current Linux users', it is 'kernel developers and other experts'. A relative outsider can, with work and the appropriate general cultural background, decode the in-joke to guess what it means, but that doesn't make it any less of an in-joke.

(And if you do not know what 'Yama' is in the context of the kernel, you will probably be completely lost.)

An in-joke may have character and voice, but it neatly illustrates that merely having character and voice doesn't make writing (or messages) good. The first goal of good writing is to be clear and informative. Then you give it voice.

(This is of course not a new or novel thing in any way; lots of people have been saying this about technical writing for years. I just feel like adding another little brick to the pile.)

Comments on this page:

I agree wholeheartedly. I think that's why I've had the most success picking up new skills from the "For Dummies" series of books as opposed to books of better technical quality.

The other place where dryer, blander writing is better is in release notes. Mobile apps in particular seem to focus on humorous or downright silly release notes that provide almost no useful information. "Fixed some bugs" is not really helpful in this context.

By liam at unc edu at 2015-02-13 09:25:21:

An example of the fact that good technical writing doesn't have to be characterless is the Coherent manual (can be found here - Coherent was a Unix clone pre-Linux which was noted for it's excellent manual. Many people bought the software just to get the manual.

Written on 11 February 2015.
« ZFS can apparently start NFS fileservice before boot finishes
The technical side of Python metaclasses (a pointer) »

Page tools: View Source, View Normal, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Wed Feb 11 22:19:01 2015
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.