+1

Documentation.md

reviewed

··· 21 21 - [Use active voice](https://developers.google.com/style/voice): make clear who's performing the action. 22 22 - [As you are working in a team, then you have to address the problem of shared understanding](https://surfingcomplexity.blog/2022/11/24/writing-docs-well-why-should-a-software-engineer-care/). This is where documentation come in. 23 23 - [Use the imperative mood in descriptions and instructions](https://twitter.com/kepano/status/1751354613041872985). Use concise action-oriented sentences, written from the user's perspective. 24 24 + - When writing instructions, anywhere you say "You should X" or "You can X," replace it with the imperative mood of the verb. 24 25 25 26 ## Resources 26 27

+7 -3

Writing.md

reviewed

··· 10 10 - [**Be concise**](https://stephanango.com/concise). Understand the topic you're writing about. [Use simple words and sentences](http://www.paulgraham.com/simply.html). Put the most important things first. Never use a long word when a short one will do. Explain ideas in simple terms, strongly and clearly, so that they can be rebutted, remixed, reworked — or built upon. Concise explanations accelerates [[making decisions]] and make ideas useful. One idea can more easily be combined with another idea to form a third idea! 11 11 - **Be Useful**. Before you start writing, ask yourself: What purpose does this serve? Who is going to read it? What do they need to know? 12 12 - **Be specific**. Avoid vague language (remove qualifiers). Cut the fluff. Delete unnecessary words. Say what you mean. Make positive statements about reality. 13 13 + - You can almost always replace an adverb with a better, more specific verb, or describe what you mean instead. Remove the adverb and commit to saying whatever you're saying. 14 14 + - Instead of using constructions with "of" or "for", rewrite the sentence to put more information before the noun. 13 15 - **Be consistent**. 14 16 - **Add rhythm**. Vary the sentence length to break the monotony. 15 17 - Use the active voice. 16 18 - Write in a conversational tone. Think about readers when writing. 17 19 - [Divide things into small chunks and if you have multiple points in a text, number them to make replies easier](https://slatestarcodex.com/2016/02/20/writing-advice/). List the points you want to make in a logical order. This allows you to remove the clutter and avoid confusion. Use the [Minto Pyramid](https://scqa.lifeitself.org/) or another standard structure like this one: 18 18 - - [Define a clear thesis](https://www.cs.columbia.edu/~hgs/etc/writing-bugs.html). State the main point before you give the reasoning that leads to it. 19 19 - - Support your thesis with arguments. 20 20 + - Decide what you're actually saying. [Define a clear thesis](https://www.cs.columbia.edu/~hgs/etc/writing-bugs.html). State the main point before you give the reasoning that leads to it. 21 21 + - What is your main point? Who are you writing for? 22 22 + - Support your thesis with arguments. Repeat yourself (within reason). Look for ways that you can restate your point, clarify, or provide closure for the reader. 20 23 - Declare and reject the antithesis. 21 24 - Conclusions. 22 25 - Use positive language rather than negative language. 23 26 - Human beings are wired to respond to storytelling. A story arc is a way to structure ideas to tap into this response, typically by describing a change in the world. This applies to everything, e.g: [[Public Speaking]] 24 27 - Don't fully think through your ideas before writing. It's inefficient. The best way to think is by writing. It compels your brain to connect the dots. [Write whatever helps you think better](https://twitter.com/eugeneyan/status/1256828197410201601). 25 25 - - [Don't try to _persuade_ people that the idea is true/good. Instead, try to accurately _describe_ where the idea came from, the path which led _you_ to think it’s true/plausible/worth a look. In the process, you'll probably convey your own actual level of uncertainty, which is exactly the right thing to do.](https://www.lesswrong.com/posts/Psr9tnQFuEXiuqGcR/how-to-write-quickly-while-maintaining-epistemic-rigor) 28 28 + - [Don't try to _persuade_ people that the idea is true/good. Instead, try to accurately _describe_ where the idea came from, the path which led _you_ to think it's true/plausible/worth a look. In the process, you'll probably convey your own actual level of uncertainty, which is exactly the right thing to do.](https://www.lesswrong.com/posts/Psr9tnQFuEXiuqGcR/how-to-write-quickly-while-maintaining-epistemic-rigor) 26 29 - Be self-aware about your knowledge level on a topic, and say "I'm not sure…"" when you are not sure about something. 27 30 - Separate the processes of creation from improving. **You can't write and edit**. Write the first draft fast, then iterate on it editing things. Much of this editing will be cutting, and that makes simple writing even simpler. 28 31 - [Beware of "this"](https://www.lesswrong.com/posts/5e49dHLDJoDpeXGnh/editing-advice-for-lesswrong-users). Scan your words for words like "this" or "that", and when in doubt about clarity, replace them with whatever their intended antecedents are. 29 32 - You can use tools like [Hemingway](http://www.hemingwayapp.com/) or [Ludwig](https://ludwig.guru/) to improve. 33 33 + - [The point of editing](https://evaparish.com/blog/how-i-edit) is to think about how you're using language and to make choices that suit the message you want to deliver, not to unquestioningly follow rules—mine or anyone else's. 30 34 - When writing tutorials or guides, use the second-person and describe actions to a user. These types of content talks to people when humans can't. [Technical documentation follows the same rules than normal writing](https://developers.google.com/tech-writing/one). 31 35 - [Make it fun](https://davnicwil.com/tips-for-making-writing-more-fun/)! 32 36 - The skills you learn by writing transfer to speaking. Being good at speaking makes you more persuasive.