CS486 - Senior Capstone Design

Software Design Spec Document Guidelines

Executive Summary: What are we working to produce here?

A concise 5-15 page document detailing how you plan to build your software, including all classes, methods, etc. Includes enhanced timeline. A technical reader should get clear feeling that you have the implementation well in-hand and are on track to success.

Normally, this document is not delivered to the customer, but is used by the team internally to organize the implementation process. It represents the outcome of the software design phase and should provide a spec for various modules, classes, and functions that is detailed enough to hand off to independent implementers for implementation.

Software Design Spec Document

Customer Concept Requirements Functional Spec Detailed Design Code

At this point, we have arrived at the last two stations in the above graphic showing overall phases in the design process. Of course, in the modern Agile design environment, we iterate quickly through this process --- but not so quickly that we fail to do thoughful design in our rush to get something coded! The Design Document plays a valuable role here: the team has taken the functional spec and has decided on an appropriate software architecture with which to implement the functions specified, i.e., has defined modules, classes, methods, and appropriate interfaces that --- working as a whole --- will implement the design. Getting the outcome of this design process is important. First, just by getting it all down in black and white, it ensures that the whole team is on the same page when it comes to implementing the product. Second, it provides a mechanism for communicating the design to the coders, who may not necessarily be (only) the designers; this is particularly true in larger corporate contexts. Thus, the Design Document needs to provide a level of specification that is adequate for coding the product without having knowledge of all the previous phases of the design.

Because things CHANGE in the course of a design, this document should evolve as your get various pieces implemented and integrated, always reflecting the actual design. This is PARTICULARLY important on large projects where this document is the primary way for one team member to know how other modules are evolving. Moreover, keeping this document current can pay off: at the end of the project, your client will likely want an "As-Built Report" as part of the final deliverable. This report is essentially your (up-to-date) design spec, detailing the internal guts of what you've implemented.

Design Spec Document: Suggested Content Outline

As a starting point, the Design Spec should include:

1. Cover page

2. Table of Contents

3. Introduction -- Executive summary that briefly but concisely (1-2 page) describes the overall client business problem, objective of the project, and high level requirements. What you are shooting for here is a condensed summary of the longer descriptive section (problem statement, solution statement, etc) of the initial requirements document. The goal here is simple: you want to "remind" readers what the overall problem context is, so that the technical details you are about to present can be properly interpreted. A person quite unfamiliar with your project should be able to get the basic overall idea, challenges and constraints from reading this.

4. Architecture Overview -- You don't want to jump straight into detailed class and method descriptions! If someone is going to implement your spec, it's important for them to have the "big picture" of your architecture. How did you break the problem up? Introduce and describe briefly each of the main "modules" of the system. Tie it all together with a walk-through of how all of the modules work together to create overall system behavior. Some good things to have here are a diagram showing the modules and their inter-relations, i.e., how data flows between them. Another nice thing can be a mocked up screen shot or two in order to give an idea of how key situations will look when finished.

5. Detailed Module Descriptions -- Now take it down another level. Have a subsection for each of the modules you introduced earlier, and tacke each on in detail. Again, the idea is that you could cut one of these sections out of your document, hand it to a coder, and expect a fully implemented model to come back a week later. To this end, you want to give a detailed software description.

  1. Overview: A short paragraph or two where you talk about the overall goals of the module, and briefly outline what part it will play in the overall application. The idea is just to put the module in context a bit here.
  2. Class Overview: Give UML and/or textual descriptions of the overall classes or functions in the module and, for each, briefly describe what it does, who uses it, and so on.
  3. Detailed info for implementation: Describe the public interface to each class, i.e., spec out the methods in the public interface. By explicitly outlining the services that the class will provide, you are providing a concise implementable spec for the class. For each method, give a brief description of what it does: what params it takes in, what processing it does, what results it is expected to return.

6. Implementation Plan --- Basically, an implementation timeline. Give a brief sketch (1 page or so) that succintly lays out your plan for implementing this spec. This could be a Gannt chart showing which modules get implemented when, and key points at which finished modules are tested and integrated. It is also very useful to annotate modules in the timeline with specific team members who you expect to be working on them at any given time.