Introduction
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).
Resources
I googled “how to write a good technical design document” and picked a couple that were good and complemented each other:
- https://www.range.co/blog/better-tech-specs
- https://medium.com/machine-words/writing-technical-design-docs-71f446e42f2e
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.