Writing a good design document

Role and Benefits of Design Docs

• Many see design docs as essential for clarifying thinking: writing exposes sloppy reasoning and can dramatically improve ideas.
• Several people say they write docs even when no one else will read them (“forensic design documentation”) because it crystallizes their own understanding.
• Some advocate writing docs and even user/API documentation before code to ensure the problem and interface are truly understood.
• Others extend this to a broader “design culture” where engineers avoid undocumented, ad‑hoc projects and leaders who can’t plan in writing.

What Makes a Good Design Doc (Structure & Content)

• Popular patterns:
  • “Onion” model: (1) problem, goals, non‑goals and requirements → (2) functional spec (external behavior) → (3) technical spec (internals).
  • BOO / strategy-style: background/problem, objectives/constraints, then actions/solution.
  • Sections for alternatives considered and why rejected, explicit non‑goals, stakeholders, assumptions, and risks.
• Strong docs make the hard solution seem obvious by the time it’s presented, but don’t overload readers with the author’s full struggle; rough work can live in appendices.
• There’s disagreement over whether to lead with the conclusion (for quick orientation) or with the reasoning (for persuasion and shared understanding). Many suggest: short summary up front, argument/details below.
• Debate over the “proof” analogy: some like informal correctness arguments; others think calling design docs “mathematical proofs” is pretentious and that their real job is to present a feasible, sufficient (not perfect) solution and tradeoffs.

Documentation Lifespan, ADRs, and Maintenance

• Concern that big design docs quickly rot into “design archaeology.”
• ADRs (Architecture Decision Records) are proposed as lighter-weight, code-adjacent records of specific decisions, easier to update or supersede over time.
• One camp says design docs are snapshots and shouldn’t be constantly maintained; when reality changes, write new docs. Another argues that refusing to maintain design records is effectively pushing complexity and confusion downstream.

Writing Culture, Meetings, and Amazon-Style Practices

• Several praise Amazon’s PRFAQ style (working backwards from the customer, narrative documents, technical appendices) and the practice of silent reading at the start of meetings as a forcing function for preparation and better writing.
• Critics call in-meeting reading a waste of synchronous time and infantilizing, arguing docs should be read beforehand and meetings reserved for discussion.
• Defenders counter that in practice people don’t pre‑read, calendars are overloaded, and meetings are often the only reliable forcing function for attention; reading together ensures a shared baseline and avoids re-explaining basics verbally.
• There’s broad agreement that requiring a written doc at all greatly improves meeting focus compared with purely verbal or slide-based sessions.

Metrics, Resumes, and “Replace Adjectives with Data”

• The article’s “replace adjectives with data” advice triggers a long tangent about quantified bullets on resumes (“decreased X by N%”).
• Many hiring managers feel most such numbers are unverifiable or exaggerated and have grown numb or skeptical. Some now penalize resumes overloaded with generic “X by Y%” phrasing.
• Others strongly defend concrete metrics: even noisy numbers provide a starting point to probe impact and business awareness in interviews.
• Several note that candidates and recruiters optimize for what passes automated or non-technical screening, so metric-heavy resumes are a rational response to flawed hiring funnels, not purely candidate vanity.

Tools, LLMs, and Writing Skills

• Some describe workflows where they brain-dump, use an LLM to impose structure, then heavily rewrite and compress; the value is in editing and cutting, not in raw generation.
• Others stress traditional technical writing training: ruthless editing, fewer words, shorter paragraphs, and continual practice.
• Diagrams are mentioned as underused: for many problems, a clear drawing can communicate design faster than prose.

Skepticism and Gaps

• Several readers wanted concrete, real-world examples of great design docs; they note that many “how to write design docs” posts are high-level and somewhat cargo-cult.
• There’s also cynicism from people who’ve seen RFC/design-doc processes become promotion artifacts or bureaucratic theater rather than tools for alignment and better systems.