- Tags:: Writing Is Thinking
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.
References
-
My favorite short ref: Refactoring
-
-
For good structuring: The Pyramid Principle.