+2

Design Docs.md

reviewed

··· 26 26 - In many docs a diagram can be useful. 27 27 - The steps in the life-cycle of a design document are: Create, Iterate, Review, Implement, Iterate and Learn. 28 28 - [The RFC and feedback should be posted publicly. Everyone can join the discussion. The goal is to include as many people as possible to access more points of view and spread the knowledge simultaneously](https://candost.blog/how-to-stop-endless-discussions/). 29 29 + - [Structure your design docs with clear organization where every sentence flows obviously from the previous ones](https://grantslatton.com/how-to-design-document). Each paragraph should represent a single, clear idea. Model the reader's current understanding and guide them to your perspective by anticipating and preemptively addressing potential objections. 30 30 + - [Ruthlessly edit design docs to reduce length by ~30%](https://grantslatton.com/how-to-design-document). Use short, focused paragraphs that can be summarized in one sentence. Move complex calculations and supplementary details to an appendix to keep the main document immediately comprehensible. 29 31 - The process brings accountability. Whoever writes the proposal should be kept accountable. When people know that they will be accountable, they tend to approach more carefully and consider different aspects seriously. Ways to hold yourself and others accountable for showing your work: 30 32 - Start by stating the problem you're trying to solve and why. 31 33 - Enumerate what your goals were and what principles you followed.

+1

Documentation.md

reviewed

··· 25 25 - Ask the below two questions before writing: 26 26 1. Who am I writing this for? 27 27 2. What are the top 1-3 takeaways after someone's read? 28 28 + - [Model your reader's current understanding and guide them to your perspective](https://grantslatton.com/how-to-design-document). Anticipate and preemptively address potential reader objections. The goal is to convince readers (especially yourself) that your approach is optimal through clear logical progression. 28 29 - [Write simply](https://zodvik.com/posts/on-writing-well/): 29 30 - Use fewer than 30 words per sentence. 30 31 - Use ordinary words and simple sentences.