Last
updated: April 28, 2006
Software Design Specification
General Documentation Issues
-
Documents need to have a clear organization with major sections numbered and titled (1.0 Introduction, 2.0 Design Overview, etc.)
-
Provide meaningful names for the elements (components, functions, etc.) shown in your design model. Don't just call them P1, P2, etc.
-
Review your design to ensure that it accurately reflects how you want the requirements specified in the Operational Specification implemented. Also check to ensure that you fully implement the Operational Specification.
-
Although we are not expecting professionally formatted documents, spending a little time structuring the document for readability will be appreciated. Try to do some minimal formatting of your document's layout. Include white space, have consistent line lengths, etc.
-
Make diagrams neat and legible.
-
Every illustration or diagram must be referenced from your text. However, ensure that you do not just make a passing reference to a diagram. The text that accompanies your diagram should explain the import elements illustrated in the diagram. Describe how things are intended to work and why you selected the arrangement of elements you did.
-
Spell check the document and read it over for correct grammar and intended expression of ideas.
-
You may have some difficulty in mapping an Operational Model to an inappropriate or incomplete Design Model.
-
Your first cut may produce design elements that are too macroscopic. That's an OK starting point but work for more granularity. Strive to achieve design elements that are relatively single purposed.
-
The ultimate goal of the design process is to document in the Design Specification all the information that someone else would need to build a system that implements the requirements defined in the Operational Specification.
-
A complete design model will provide for all of the operations documented in the Operational Specification. It is unlikely that you'll get all the operations documented on the first or even second try. This is definitely an iterative process.
Annotated Outline
Title Page
Table of Contents
Revision History
Introduction (Section 1 of the document)
-
Purpose of the document
-
References & Applicable Documents
-
Definition & Terms
Design Overview (Section 2 of the document)
-
The overview needs to provide useful information about the design approach used for the product. Don’t just repeat the high level requirements or capabilities that were presented in the Operational Specification. Tell how those capabilities are implemented or provided by your design. The overview is an “executive summary” that gives a really good idea, at a high level, of how you've organized your solution. The overview should be up to a page or two in length and should include a high level diagram showing major elements or pieces of your program and their interaction. Pieces could be classes, subsystems, or some other meaningful part of a program's decomposition. This will be the first decomposition shown. Addition levels of decomposition will be presented in the remaining sections of the Design Specification.
-
You should minimally address the relationship between various parts of your system and its environment including the operating system, users, file system, communications facilities, and other programs to which it interfaces (as appropriate)..
-
Don’t get into too much detail.
-
Think of the representations as models. A model does not have to provide all the details that you will see in the finished product, however, it does need to encompass all aspects of the system it represents.
Design Model Details (Section 3 of the document)
-
Compared to what was presented in the previous section, the Design Model Details section presents a more in-depth representation of the design.
-
A design is not a restatement of what various commands or user operations do. That information is contained in the Operational Specification.
-
Details need to be provide that show how you have decomposed the design. You will probably need to provide designs that address both program decomposition and internal data structures used by the program. Diagram needs to expose the architectural structure of your solution, e.g. many separate programs that operate on commonly accessible files, or a set of classes that create an object-oriented implementation. You should eventually reach a level of decomposition that addresses specific design elements such as functions or methods residing in a class and significant internal data elements.
-
Text needs to discuss how the design responds to a specific user request (operation) presented at one of the program interfaces. This provides animation of your design and it should represent the dynamic response of it to user requested operations. Animation is one method that is useful in validating a design.
-
You will need to identify the program's "modular" structure and the relationships that exist within it.
-
You need to identify the specific details of interfaces to modules, and external interfaces that have not be specifically defined in the Operational Specification.
-
The amount of detail you include for the various design elements may vary. In some case you may need to identify a specific algorithm that is to be used. In other cases you may not. In some cases you may want to specify the type of data structure used by program elements. In other cases you may not. Specify in detail those things that require critical thinking and are best worked out before your transition to the programming phase of your project.
