- Tags:: [[Writing is thinking|Writing Is Thinking]] ## My own compiled tips - Almost always have a **What, Why (now) sections** (see [[Software documentation|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. a developers guide to writing well|Refactoring]] - [Technical Writing  |  Google for Developers](https://developers.google.com/tech-writing) - [[The elements of style|The Elements Of Style]] - [[On writing well|On Writing Well]] - ![[cover_how_to_write.png|400]] - For good structuring: [[The pyramid principle|The Pyramid Principle]].