Design Documentation

1. Recall that: A spec is a relationship between IO, expressed using discrete math, logic, and grammars. We prefer it to be declarative. But, occasionally we do use an older version of a program to be a spec for a new version to be built, with additional spec details added.
2. A design is a how-to expressed in a high-level notation, far higher than typical programming languages such as C++ and Java.

1. Consider a design to be a VHLL program, i.e., executable.
2. Psuedo Code http://en.wikipedia.org/wiki/Pseudocode
3. All programs, in particular "First Time" Programs, should be prototyped in VHLL.
4. Python and other languages at that "level" are acceptable, but make up an appropriate VHLL, at a higher level.

"A design rationale is the explicit listing of decisions made during a design process, and the reasons why those decisions were made. Its primary goal is to support designers by providing a means to record and communicate the argumentation and reasoning behind the design process. It should therefore include:

• the reasons behind a design decision,
• the justification for it,
• the other alternatives considered,
• the trade offs evaluated, and
• the argumentation that led to the decision."
• [from Wikipedia]

1. By now you have read a number of peer-reviewed academic papers. Follow their style; e.g., follow JML fmdoc.pdf. Technical Reports are more generous with page layouts, and such.
2. Cover Page
3. Abstract
4. All pages, except cover page, are numbered Table of Contents (TOC) Sections: Sections must be numbered also; Typical: Three levels; too many: > 5 First Section = "Introduction" 1. Last Section = "Conclusion" Unnumbered "References" Section; Cite them. See Chicago Manual of Style. 7 Misc

1. http://en.wikipedia.org/wiki/Design_rationale. Required Reading.