Design docs, RFCs and ADRs · Proficient · Lesson 76 of 98 · about 2 hours
Why design docs exist and when to write one
After this you can decide whether a change needs a design doc and explain what the document is for to someone who thinks it is bureaucracy.
Why it matters
A design doc is a tool for thinking and for getting feedback early, not a deliverable. Google's engineers write them for any change where the cost of getting it wrong is high or where several teams are affected, and skip them for changes that are obvious. Focus on the purposes: finding problems before code is written, reaching consensus, spreading knowledge, and leaving a record of why. If a document serves none of those, do not write it. Trap: writing the design doc after building the thing. Then it is documentation, which is useful, but you have lost the main benefit.
How to use this resource
The clearest description of what a design doc is for, what goes in it and when not to write one. No good video covers this as well.