Writing a good design document
a day ago
- Design documents are technical reports that outline implementation strategy with trade-offs and constraints.
- The goal is to convince the reader (and the author) that the design is optimal, akin to a mathematical proof.
- Good organization is crucial; avoid 'spaghetti design docs' by ensuring each sentence flows logically from the previous.
- Anticipate readers' objections and preemptively address them to guide their understanding.
- Edit ruthlessly to remove unnecessary words; aim to cut ~30% from the first draft without losing information.
- Practice extensively; Amazon's doc-writing culture (silent reading with red pen) forces improvement.
- Use short paragraphs with one idea per paragraph, allowing readers to compress information in short-term memory.
- Include an appendix for complex calculations or simulations, keeping the main body clean and accessible.
- Worked example demonstrates editing verbose text into a concise version conveying the same information.