“Here’s a story from the early days of Amazon Web Services: Before writing any code, engineers spent 18 months contemplating and writing documents on how best to serve the customer.”
Eighteen months of documents before a line of code sounds like waste until you count the rewrites it saved. Yan’s structure is simple. Say why it matters, what you’ll do, and how. Most design docs open with the how and never answer the why. That’s how teams build the wrong thing efficiently.