In “My Favourite Usability Books” I recommended a German article about writing well. One commenter asked for English resources and I decided to translate it (with consent of the author Susanne “Su-Shee” Schmidt). Not everything is applicable in English though. The mindset is different (e.g. complicated and convoluted sentences are often considered “good” German, especially in academia and intellectual circles; popular science is looked down on) as well as what constructs are common in the language.
I denote differences to the German original in square brackets [like this]. Here we go:
Everyone wants it – hardly anyone writes it: A straightforward technical documentation, easy to read and understand. How do you write a good technical documentation? And what does “good” even mean?
Wanted: A subject
You’re writing well, when people understand what you’re writing. You’re writing well, if you convey meaning in sentences with at most one comma and one loanword each. You’re writing well, if you write often, if you practise. Writing well is neither an elusive talent nor divine inspiration: Writing is a craft. There are simple rules for writing well and that’s why you can learn to write. For all kinds of texts there’s one set of rules to apply – regardless whether the text is written about technology, philosophy or a diary: The first rule states: No passive voice. “text is written” – pray tell me, by whom? And why? “A segfault was triggered.” By what? As a result of which problem? What was the cause? It’s not for naught that sentences have a subject (the “agent”, the one who acts) and an object (on which is acted upon) and a predicate (the verb). You use passive when there’s no subject – and that’s a rare case indeed. A simple syntax highlighting in your favourite editor suffices to make your style more straightforward. There, a hidden passive! Who makes what more straightforward? Authors can highlight bad style and passive voice with syntax highlighting in Vim or Emacs. Better!
Especially in complicated technical descriptions readers want clarity and precision, no wait: accuracy. Why use a loanword if you don’t need one? Readers want clarity and accuracy. Unmistakable. That’s the second rule: Don’t sloterdijke and don’t habermas! Modern philosophy – I call it postmodern brain-wanking – is often unreadable: “The subject generates in its metaphysical relevance a reziprocal rhizoe for the deprivation of itself.” That’s not necessary: Many famous philosophers communicate without loanwords and overwrought sentences because clarity is their goal. Of course you can get extra technical – manuals and howtos are chock full of technical terms. Authors conveniently forget that readers want to understand their books and texts. You write a text for readers, not against them.
Relative clauses make a sentence relatively long
Summary: No passive, as simple and to the point as possible. That’s difficult and may sound unfamiliar – aren’t you only writing well, if you’re writing complicated sentences? Isn’t it only scientific if it sounds scienc-y? No. Humbug. In 1954 Hemingway received the Nobel prize for his collection of subject- object – predicate sentences and if it’s enough for Hemingway, it should do for us. Each Steven’s demonstrates: Clear sentences. Never more than 2, at the very most 3 lines. Each sentence ripe with knowledge. Who rules grammar as well as Thomas Mann may write more than 3 lines. The rest of us use less than 3 lines per sentence and split, as soon as we start a relative clause, the sentence into several sentences. Conseqently: The rest of us use less than 3 lines per sentence. As soon as we start a relative clause, we split the sentence into two. That way you also avoid learning rules for commas. You don’t need to learn them, when you don’t need commas.
Wuddayacallit: Empty words
The next trap: Don’t blabla but inform. In English there are a number of empty words that you can sprinkle into your texts in whatever quantity: really, actually, anyway, like, just, about – all words that allude to the fact that the following is inexact: “about” is an inexact time or amount specification. “The compiler takes about 3 hours”. How about: “If the CPU is faster than 1GHz, the compiler takes 2.45 minutes. Is the CPU slower, it’ll take 3.30 minutes. With a 486 you better let it run overnight.” There you go. Now the reader knows what to expect!
Equally superfluous: Adjectives. This is where it’s getting hard for many writers as adjectives make the text snappy and lively. But that’s just the first impression: Adjectives make the text turgid and long-winded and squeeze the last breath of imagination from the reader – just don’t imagine that passion yourself, better spell it out: “He kissed her wonderfully rounded belly button passionately and wildly, she moaned deeply and ..”. That’s how you geht a pulp fiction tacky trophy. Verbs make the text lively, because they express movement and action. Why not write: “He fucked her, she bit him and groaned into the night.” What they actually do is left to the readers imagination.
Analoguously you can remove adjectives such as “the great editor” in technical texts – if the editor were shabby, you wouldn’t be writing an article. “The outstanding compiler” or even “fast comiler” are just as superfluous: Fast compared to what? Why does the auther think the compiler’s outstanding? Instead list the features that distinguish a compiler or editor from the crowd: “The nogglywoggly doublefroop makes the gcc a fast compiler. All other compilers still globble the gnarfel and that makes they slow, because no shlobmob is optimized.” Harumpf. One passive. “Because the function for optimized shlobmob doesn’t exist.” Or better still: “Because no developer has implemented the function for optimized shlobmob.” Ah, the feature’s missing!
[Omitted: Paragraph on avoiding English loan words unless they are important keywords and more readily understood than a German translation.]
All the tips together: No passive, clear, simple sentences, few loan words, remove adjectives, use verbs instead and only use English loan words, where they are essential. Something missing?
Searching: Verbs used as nouns (“nominalisation”)
[In German you can turn any verb into a noun by changing the ending. It doesn’t carry over to English well, but I wanted to translate the examples anyway.]
Yes! One ability of the German language is the usage of the application of the nominalisation of verbs! Often inexperienced authors write, in order to seem more respectable, sentences like this one: “By means of the compilation the software turns into a binary” – you can say that clearer and simpler: “The gcc (subject – who?) compiles (verb – what happens?) the sources (object – whom?) into a binary (target of the action).” Now you know, who does what with what goal. My sentence could also be shorter: “Often inexperienced autors”.. Who does what is introduced late in the sentence: “Inexperienced authors often write..” Often? Away with it. “Inexperienced authors write sentences with nominalisated verbs to sound more respectable.” There you go. Who does what with what and to what end? All bases covered.
For your text editor everything at a glance:
The golden rule is: Delete, shorten, remove! A text almost always improves, when the author shortens rigorously. Sentence too long, more than 2 commas and it’s not a list? Split it into two sentences. Too many adjectives? Discard them, replace them with verbs. Nomalisated verbs and loan words? You can be shorter, clearer and more precise: Abolish them. In the beginning the sentence seems choppy – one could also say: crisper, shorter and you first have to get used to that.
How can you spot style problems automatically?
[Omitted: Exhaustive list of what you can configure your text editor to highlight so that you can easily spot bad style.]
For advanced writers there are a few more rules. As you can automatically highlight the ones listed above, those for beginners, you can discard them before you’ve finished typing. If you’d like to read more: [Omitted: German book recommendations]
For a better style in English read the classic “On Writing Well” by William Zinser – btw a relief for anyone who can’t keep track of tenses in relative clauses or passive: Not good style anyway. To those who want to know how authors wrestle words and use stylistic devices, I recommend “On writing” by Stephen King.