writing-design-docs

Writing a design doc requires following a six-component structure: problem, background, values, options, recommendation with rationale, and open questions. This template-driven approach ensures stakeholder alignment by evaluating tradeoffs before selecting an architectural direction.

A problem-statement design doc captures requirements, values, options, and tradeoffs before selecting an approach. Use it for non-trivial technical decisions like feature planning or architectural direction setting where success criteria and alternatives must be explicitly evaluated.

Frame a technical problem for stakeholder alignment by defining the problem, desired behavior change, success criteria, and out-of-scope items. Use staged collaboration to invite review with honest open questions instead of seeking approval or hiding uncertainties.

Writing a design doc requires comparing architectural alternatives by walking through values, options, and tradeoffs. The recommendation's rationale must explicitly tie back to the defined values, ensuring the chosen approach is evaluated against success criteria.

You can use a template for drafting technical design documents by filling the included template file section by section. This template-driven writing approach covers the six-component structure to produce a document stakeholders can critique and refine.

When creating a design doc for feature planning, avoid jumping straight to a preferred solution without evaluating tradeoffs. Do not hide uncertainties; instead, present honest open questions and explicitly define out-of-scope items to invite meaningful stakeholder review.