Writing a good design document | Hacker News
Each section should follow from the previous. The design doc should justify to the reader (and author) that the problem is understood, the requirements are necessary and sufficient, the functional spec meets the requirements, and the technical spec implements the functionality and non-functional requirements. As a corollary, if one section has a fatal flaw, there is no need to read on. If the problem is misunderstood, then the functional spec is likely wrong. If the functional spec doesn't meet the requirements, then the implementation is moot. The issue I see very frequently is technical design documents that provide only the final section—a simple description of the system that will be built. As a design reviewer, there is limited feedback I can provide on such a design. Sure, it's a system, but will it solve the problem? Does the team even agree on the problem to be solved? Layer one also explicitly identifies stakeholders, and describes the current (AS-IS) situation with annonated
Each section should follow from the previous. The design doc should justify to the reader (and author) that the problem is understood, the requirements are necessary and sufficient, the functional spec meets the requirements, and the technical spec implements the functionality and non-functional requirements. As a corollary, if one section has a fatal flaw, there is no need to read on. If the problem is misunderstood, then the functional spec is likely wrong. If the functional spec doesn't meet the requirements, then the implementation is moot. The issue I see very frequently is technical desi
Explore this link on the map →