3 ms·

I don't think they are mutually exclusive? Design doc is broader. It's goal is communication. Sometimes you need to communicate other than in code. Diagrams,

• corytheboyd 2y ago
  Agree. It’s very hard for anyone who isn’t the author, or otherwise intimately familiar with the code, to understand changes at a glance. The reader needs high level explanations and documentation to quickly build the correct mental model to understand the change in context. If you can look at 1000 lines of diff and accurately tell what it’s doing, and much more importantly, the upstream and downstream implications… you’re either lying, or somehow work in a perfect hermetic vacuum of verifiability that I am very jealous of.