Practical Design Docs

Refactoring English book cover

Presented 2025-10-16

https://slides.refactoringenglish.com/

What’s the point of design docs?

What’s the point?

  • Identify design issues early
  • Coordinate work across multiple developers/teams

What’s the point?

  • Strengthens design ability
  • Explains design decisions to future maintainers

What’s the downside of design docs?

Design doc costs

  • Difficult / time-consuming to write
  • Difficult / time-consuming to review
  • Difficult to maintain

Not every project requires a design doc

  • Choose which projects are worth the tradeoff
  • Invest in design docs proportional to project complexity

When is a design doc valuable?

  • More stakeholders / collaborators

When is a design doc valuable?

  • High project complexity
  • High technological ambiguity

When is a design doc valuable?

  • High cost of design flaws

When is a design doc valuable?

  • Long code longevity

When is a design doc less valuable?

  • Experimental / exploratory work
  • Fast short-term velocity
  • Unambiguous, low-complexity work

What if everyone around me hates design docs?

Objections to design docs

  • “I’m a genius, so everyone should follow my lead”
    • Translation: I don’t want to relinquish control

Objections to design docs

  • “I write code, not documents”
  • “I can’t know the design until I build it”
    • Translation: I enjoy experimenting with code and don’t enjoy writing.

Objections to design docs

  • “It’s just extra overhead”
    • Translation: I’ve never seen effective use of design docs

Fostering a documentation culture

  • Documentation requires trust
    • Trading easily-measureable short-term results for hard-to-measure future benefits
    • Investing in documentation is a risk

Fostering a documentation culture

  • Earn trust through other documentation initiatives
    • e.g., documenting processes, documenting existing architecture
  • Earn trust through more obvious wins
    • e.g., automated tests, automated deploys, continuous monitoring

Fostering a documentation culture

  • You need some management buy-in for design docs
    • Otherwise, it’s hopeless

Fostering a design doc culture

  • Do the heavy lifting initially
    • Write the first design doc
    • Drive the review process
    • Show appreciation to people who participate

What tools do I use?

  • Tool should:
    • Make it easy to write
      • Don’t get bogged down learning the tool itself
    • Creates a permalink (authoritative URL)
      • No passing around files / obsolete versions
    • Has version control
    • Supports reader comments

Design doc tooling

  • Lazy answer: Google Docs
    • Easy to work with
    • Creates a permalink
    • Has version control
    • Supports margin comments

Design doc tooling

  • For dev-only team: Markdown + Static site generator
    • Review using code review tools
    • Publish to a consistent URL

What goes in a design doc?

What goes in?

  • Imagine a junior engineer will do all the work
    • What do you need to catch before code review?

What goes in?

  • Then, imagine that you will do all the work
    • What did you hand-wave when imagining someone else would do it?

What doesn’t belong?

  • Things you’ll catch in code review
  • Team-wide conventions

What doesn’t belong?

  • Examples
    • Code style conventions
    • Minor dependencies (e.g., standard library modules)
    • Class diagrams
    • Filenames, function names
    • Folder locations

Inverted pyramid

Inverted pyramid

Choose which sections to include

  • I’m including many possible sections
  • You’d generally only include a subset that adds value to your project

Contents: Title

  • Name for your project
    • The way you’ll refer to it in conversations
  • Ideal qualities of a name
    • Short
    • Distinctive
    • Evocative

Contents: Title

  • Example: Add a caching layer between your application server and database server
    • Good Title: TopDrawer
    • Bad Title: Project Flying Silver Horse

Contents: Document metadata

  • Who the author is
  • When it was created
  • What’s the authoritative link

Contents: Objective

  • One-sentence explanation of your project in terms any stakeholder understands.

Contents: Background

  • Why is the team taking on this project?
  • Why now?
  • Link to other design docs that depend on this work
  • Link to previous design docs for this project

Contents: Goals

  • What are the high-level goals of the project?
  • Goals are not implementation details
    • Good: Reduce median latency on queries to 200ms or less
    • Bad: Add Redis to our infrastructure

Contents: Non-goals

  • What are things readers might assume are goals but are explicitly not goals?
    • Example: “Provide a reusable cache that works across many projects”

Contents: Scenarios

  • Concrete examples of what is possible when this project is complete
    • Example: “A customer visits the website and clicks the ‘Buy’ button. The product arrives at their doorstep thirty minutes later.”

Contents: Definitions

  • Define terms readers might not recognize
    • Especially people who are newer or on partner teams
  • Ideal to minimize jargon and minimize what needs defining

Contents: Constraints

  • What are the constraints that inform your design?
    • Example: “Our servers are all RISC-V, so all code and dependencies must run on RISC-V architecture.”

Contents: Diagrams

  • Readers love diagrams
  • Invest in nice diagrams
  • Make them easy to update
    • Good: Mermaid diagram
    • Good: Google Drawings
    • Bad: Photo of beautiful, elaborate whiteboard diagram

Contents: Diagrams

  • How does this project fit into existing architecture?
  • How do the different components of this project fit together?
  • How does data flow through the system?

Contents: Timeline

  • Break it into milestones and dates
  • Prioritize parts that give stakeholders usable artifacts

Contents: Timeline

  • Example
    • Milestone 1 (2026-05-01): API is live with random data
    • Milestone 2 (2026-05-15): API is live with read-only data
    • Milestone 3 (2026-06-02): API is complete and supports reads and writes

Contents: Interfaces

  • How do clients interact with this system?
  • For a user-facing project, what does the UI look like?
    • Just sketches, don’t get bogged down on UI choices
  • For software interfaces, what are the API or CLI semantics?
  • For file-based interfaces, what is the file format?

Contents: Dependencies / infrastructure

  • What programming language?
  • Where does the code run?
  • Where does persistent data live?

Contents: Security

  • What are the trust boundaries?
  • What threats are you concerned about?

Contents: Privacy

  • What sensitive data do you handle?
  • How long will you retain it?
  • How will you protect it?

Contents: Logging

  • Where do logs go?
  • Are there different logging levels?
  • How are logs rotated?

Contents: Open issues

  • What do you still not have a solution for?
  • What parts of the design are blocked on external feedback?

Contents: Resolved issues

  • After resolving an open issue, keep it and summarize the decision

Contents: Alternatives considered

  • Don’t go overboard
    • Example: “We considered Google Cloud Firestore, but we disliked the platform lock-in and the difficulty of testing locally.”

Design review

  • What will probably happen
    • 1-2 people will review the whole thing carefully
    • 2-3 people will carefully review the parts that impact them
    • 5-6 people will casually scan it

Design review

  • Start with a single reviewer
    • Avoids bystander effect
    • Limits wasted cycles on the same issues

Design review

  • Start with a single reviewer
    • Address their questions / suggestions in the doc itself
    • Drive issues to resolution

Margins aren’t for long debates

  • If margin discussions go for more than 2-3 rounds, create an open issue
    • Use colored fonts to distinguish people
    • Call a meeting to work through thorny issues

Design review

  • Do a second individual review or send it to full team

Design review

  • Team review
    • Address their questions / suggestions in the doc itself
    • Drive issues to resolution

Design review

  • Team review
    • Call a meeting to work through outstanding open issues in person
    • Make the agenda clear in advance that you’re discussing specific issues and not relitigating the whole doc

Revising the design during implementation

  • The design doc should match the v1 implementation
  • For changes, revise the design doc
    • For significant changes, request a re-review

Design postmortem

  • After implementation, look back
  • What caused unexpected delays?
  • What issues were discovered late in the process?
  • What about the design process could have been improved?

Questions