pproenca Write Design Docs
Core Workflow
Use the design doc as a problem-solving and consensus-building tool, not as an implementation manual.
Decide whether a design doc is warranted.
- Write one when the software design is ambiguous, complex, contentious, cross-functional, likely to benefit from senior review, or valuable as organizational memory.
- Prefer a short note, issue, or direct implementation when the solution is obvious and there are no meaningful trade-offs.
- Prefer a mini design doc for small but non-obvious changes.
Gather the minimum context needed to make the design concrete.
- Identify the problem, existing landscape, constraints, stakeholders, and decision deadline.
- Ask focused questions only when missing information would materially change goals, non-goals, or trade-offs.
- State assumptions explicitly when proceeding with incomplete information.
Draft around decisions and trade-offs.
- Start with objective context and scope.
- Define goals and non-goals as explicit boundaries.
- Present the selected design from overview to detail.
- Explain why the selected design best satisfies the goals under the known constraints.
- Compare realistic alternatives, including why they were not selected.
- Cover cross-cutting concerns such as security, privacy, reliability, observability, migrations, and operations when relevant.
Keep the document readable.
- Optimize for busy reviewers who need to understand the decision, not every implementation detail.
- Link to detailed requirements, prototypes, schemas, code, or prior docs instead of copying them wholesale.
- Include diagrams or compact API/data sketches only when they clarify the design trade-offs.
- Avoid large code blocks unless explaining a novel algorithm.
Shape the lifecycle.
- Mark the document status: draft, in review, accepted, implementing, superseded, or archived.
- Suggest the smallest useful review group first, then wider review when the design is stable.
- Update the doc while the system has not shipped if implementation reveals wrong assumptions or changed requirements.
- Link amendments or follow-up docs when the original doc diverges from reality.
Reference
Read references/design-doc-guidance.md before drafting or reviewing a substantive design doc. Use it for the article-derived template, decision checklist, section guidance, and review rubric.