Guide
Software design documents worth reviewing
A software design document exists to make disagreement cheap: better to lose an argument in a doc review than in an outage. The format matters less than most templates pretend — but structure, diagrams, and a review workflow matter a lot.
The sections that earn their place
- Context & problem. What hurts, for whom, and why now. One paragraph if possible.
- Goals and non-goals. Non-goals are the higher-leverage half — they end scope arguments before they start.
- Proposed design. An architecture diagram for structure, a sequence diagram per critical flow, and an ERD if the data model changes. Diagrams here do the explaining prose can't.
- Alternatives considered. What you rejected and why — the section future readers thank you for.
- Risks & open questions. Honest unknowns invite the review you actually want.
- Rollout. Migration, flags, and the moment you'd know it failed.
Start from a finished example, not a skeleton
Chiltepin's design-doc template is a complete design document about a plausible system — every section written, every diagram rendered — so you replace content instead of staring at headings. The system-design template covers the larger system-design-document case, and the adr template records single decisions. Open any of them in the browser Studio with no signup, or scaffold locally with chiltepin new design-doc.
Design docs as code
The doc is Markdown in your repository, so it goes through the same pull-request review as the change it proposes — and because the diagrams are typed blocks, chiltepin check validates them in CI. Your AI agent can draft the first version from the codebase and your prompts, you review the diff, and chiltepin build exports the doc as a static page for reading or slides for the design review — one source, both audiences. The full philosophy is in the docs-as-code guide.
Frequently asked questions
- What is a software design document?
- A software design document (also called a technical design document or design doc) describes how a system or feature will be built before it is built: the problem and goals, the proposed design, the alternatives considered, and the risks. Its job is to get the expensive disagreements out of the way while they are still cheap — in review, not in production.
- What sections should a design doc include?
- A strong baseline: context and problem statement; goals and non-goals; the proposed design with an architecture diagram and the critical flows as sequence diagrams; the data model; alternatives considered and why they lost; risks and open questions; and a rollout plan. Short docs that nail these beat long docs that meander.
- Is there a design doc template I can start from?
- Yes — Chiltepin ships a prefilled design-doc template (plus system-design and ADR templates) as a finished document about a plausible system, so you edit content instead of inventing structure. Open it at chiltepin.dev/studio with no signup, or scaffold it locally with chiltepin new design-doc.
- What is the difference between a design doc and an ADR?
- A design doc describes a whole design up front; an architecture decision record (ADR) captures one decision — its context, the choice made, and its consequences — usually after discussion. They complement each other: the design doc proposes, and ADRs record what was actually decided as the system evolves.
- How do teams keep design docs from going stale?
- Treat them as code: keep the doc as Markdown in the repository, review changes in pull requests, and validate structure in CI. With typed blocks, the diagrams inside the doc are checkable too — chiltepin check fails the build when a diagram references components that no longer exist, which is exactly when a design doc needs updating.