Design docs versus prototypes (called "throwaway code" in this post) is a false dichotomy. Both are ways of derisking projects and aligning others on the approa

Design docs versus prototypes (called "throwaway code" in this post) is a false dichotomy. Both are ways of derisking projects and aligning others on the approach, but they work at different levels each can validate things the other can't. Here are some things I expect to see in design documents that are unlikely to show up in a prototype code review. What is the high-level description of the problem to be solved? What are the success criteria? What are the functional and non-functional requirements? What are the edge cases and failure modes and how should the system handle them? Are there multiple possible approaches and trade-offs between them? How will this code be tested and released? Prototypes, in contrast, are great for measuring performance of alternate approaches, validating unproven APIs and frameworks, and gaining practical experience with different interface design decisions. See also Leslie Lamport's article, Who builds a house without drawing blueprints? https://cacm.acm.org/opinion/who-builds-a-house-without-drawing-blueprints/ https://cacm.acm.org/opinion/who-builds-a-house-without-draw...