Introduction to Tech Design Docs


The goal of this thread is to distribute some of information about tech design standards in industry that can help us to write design docs and write them well. Other folks with relevant experience are welcome to contribute, and anyone feel free to ask questions. I am going to speak from my 2.5 years at Amazon (to be clear tech designs were a skill I was still early in developing).


I googled “how to write a good technical design document” and picked a couple that were good and complemented each other:

My notes

Those two references together say basically what I would say, so read those first. The structure I followed for the designs I wrote went a little like:

  • Introduction
  • Goals
  • Out of Scope
  • Open Questions
  • Glossary
  • Business Requirements
  • Proposal
  • Alternatives Considered
  • Metrics
  • Risks
  • High Level Estimates
  • Rollout
  • Appendices

The proposal / alternatives considered sections are the meat of the project, and it’s important to keep them well-organized and focused. Some tips:

  • It works really well when both sections have the same sub-headers, which represent pieces of the proposal with their own considered alternatives–this may be subsections of the software stack, etc.
  • If there isn’t an obvious best alternative to propose, it’s nice to omit the proposal section at least at first and leave it more up to the design review to pick the right solutions.
  • FlowChart-like diagrams can be useful for a memorable overview, but distributed systems technical proposals are really more completely captured by Sequence Diagrams. Here is a resource.
  • Diagrams should generally be followed by a detailed text description for accessibility.

Also, HIGHLY recommend using a live-collab document platform like google docs.


As an example of proposal/alternatives sub-headers, here’s the proposal subheaders (subsections of the stack / problem domain) I’d recommend for the Creditor Design Doc:

  • Authentication Platform (include sequence diagram)
  • Database Platform
  • Web Server Platform
  • Front End Platform
  • Instance Plugin Call Pattern (include sequence diagram)
  • API Intents (name, inputs, outputs) (include end-to-end sequence diagram for the primary use case(s))
  • any small miscellaneous subheaders that pop up
1 Like