Karan

2/n Design docs help w early identification of design issues, achieving consensus, document design decisions, scale knowledge of senior members, ensure consideration of cross-cutting concerns, and act as a summary artifact.

3/n They're informal and follow the general structure: 1. Context and scope — Rough overview. Keep it short. 2. A bullet list of what goals and more imp. non-goals are. 3. The actual design — Start w overview and then go into details. Focus on tradeoffs.

4/n Include a diag. to show where your sys is in context w others. 5. If it exposes an API, sketch it out. Focus on parts relevant to the design. 6. Discuss data storage 7. They should rarely contain code/pseudo code unless it's a novel algorithm.

5/n Degree of constraint — Abstract at the right level to expose solution space to make trade-offs b/w them explicit. 9. Alternatives considered — Focus on what trade-offs were made and how they fed into design decisions.

6/n 10. Cross-cutting concerns — Explain how your design impacts the concern and how they're addressed. E.g. privacy, security, etc. 11. Length of design doc — 10-20 pg for large projects; split into smaller docs if the length exceeds this no.

7/n 12. Only write a design doc when the solution is ambiguous — means of exploring the right path fwd. 13. Lifecycle — Create Iterate Review Implement Iterate Learn

8/n i. Create Iterate: Collaboration and iterating w team. ii. Review: Share w wider audience, get feedback. Formal review meeting or informal sharing w people. Allow for the experience of org to be incorporated into the design.