design-docs · architecture · writing · tech-lead
Planning
Learning to write design and architecture docs for POCs and features: the one-page design doc, ADRs, the POC recommendation, the two diagrams a doc needs, and running an async review. Every lesson ends with a real section written for a live project.
Lessons
- 1. The one-page design doc: an argument, not a manual
- 2. Goals and non-goals: the section a reviewer approves first
- 3. Trade-offs and alternatives: make the design section argue
- 4. ADRs: the fifteen-minute record for one decision
- 5. The POC write-up: a question, some evidence, a recommendation
- 6. The two diagrams a design doc needs: C4 context and container