Design Docs
Jul 2023 - Alex Alejandre

At Google, before starting a project, you write an informal document defining the design, documenting:

  • implementation strategy (in terms of problem solving, not code!)
  • key design decisions (esp. trade offs considered)

Structure not strict, but can include:

  • context and scope
  • goals, non-goals - what you want it to do, what you explicitly aren’t trying to do (e.g. don’t care about ACID)
  • the design
  • system context diagram - shows the system in the overall technical landscape (e.g. what services it context to)
  • API, data storage - if it exposes an API, sketch it. Not formal definitions, but parts relevant to the design and trade offs
  • constraints
  • alternatives considered - which could achieve similar outcomes, focusing on tradeoffs informing the decision
  • cross-cutting concerns - security, privacy, observability…

Endeavor to challenge and share the doc, getting input until it’s stable. Then rapidly iterate the doc while implementing, noting what worked or failed, shortcomings, unaddressed requireents etc.