Writing tips

My own compiled tips

Almost always have a What, Why (now) sections (see Software documentation). But don’t call them like that, summarize the what, the why and the how in one sentence: those are the titles of the sections.
Always have a table of contents! Talk in lists, have sections. It’s the map of your ideas! Use outlines in order (h1, h2, h3…). They don’t have ”:“. Be consistent on the format (underline, no underline).
You know too much! Way more than the reader. Give detail, define concepts.
Be specific. Instead of “we had a decrease”, how much decrease? How was it measured?
Use the active voice, simplify! Shorter sentences, no fillers.
Write simple. Short sentences, avoid colourful language (overdose of adjectives, adverbs), be consistent in nouns and verbs.
Writing is like coding, you need iterations and refactoring: first make it work, then make it right, and finally make it fast.
Make it easy to respond: ask explicit questions, draw attention to where you want input.