A design document has three major sections; each is outlined below. While the you can assume that the reader is familiar with pre-existing design and implementation of the code, this is not an email or wiki post - the document itself should be self-contained and able to "make sense" on its own. This is part of the reason we require a separate =.doc= file. A developer five years from now, who was not involved in a recent string of email discussions or have access to pages of ticket remarks, should be able to read the document on its own and gain insight and understanding.
{subsubsection: Section One - Overview }
- Detail the motivation - what problem is the problem, why is it
+ Start out by providing information about the motivation - what is the problem, why is it
important to solve the problem, what is the general approach? What
insights led us to the problem, what new understanding is characterized
-in how we will solve it? What are the requirements of the new enhancement, and how were these requirements gathered/identified? If the problem is related to a specific usage scenario or environment, include as salient details about the motivating scenario/environment. Try to keep the implementation details to a
-minimum here. Instead, think about what the reader will have learned
+in how we will solve it? Try to identify the requirements of the new enhancement, and how were these requirements gathered/identified? If the problem is related to a specific usage scenario or environment, include as salient details about the motivating scenario/environment. Try to keep the implementation details to a bare
+minimum when answering these questions. Instead, think about what the reader will have learned
after reading your overview about the problem itself and the tradeoffs
involved in finding a solution.
