We write everyday: Emails, documentation, blog posts, … The secret of a good text is not the writing, but the editing after writing. The suggestions on this 1-pager are based on an article by Susanne Schmidt. Click here for the German original or here for an English translation.Get PDF
Content of the 1-pager:
No one just writes a good technical document. You write a mediocre one and then edit it, until it’s good.
1. Say who is acting
A text should be written in active voice ->
Authors should write in active voice
Using passive reveals slopping research (you don’t know who acted) or conceals accountability (you don’t want to say who acted)
2. Replace uncommon words
You compose a document for readers, not against them. Employ words they can effortlessly comprehend. ->
You write a text for readers, not against them. Use words they can easily understand.
3. Remove relative clauses
We use less than 3 lines per sentence and split, as soon as we start a relative clause, the sentence into several sentences. ->
We use less than 3 lines per sentence. As soon as we start a relative clause, we split the sentence into two.
4. Remove empty words
Actually, you can basically remove filler words without losing any meaning.
-> You can remove filler words without losing meaning.
5. Replace adjectives with verbs
Adjectives seem to make texts snappy, but in reality the make texts long-winded and stale. ->
Adjectives seem to spice texts up, but in reality they bog texts down.
6. Use engaging examples
Would you rather read about 2 neighbors trying to purchase a hammer with your product? ->
Would you rather read about Doc Brown and Marty McFly trying to purchase a flux capacitor with your product.