Design Specification Template

It is expected, that when you hand this design specification in, that you have coded most of your system and that the code conforms to the architecture defined in this design specification.

This document captures the "blueprints" of what you will build as well as a detailed schedule of tasks still remaining to finish the implementation. The document should act as a bridge between business requirements and the technical details of the implementation.  Try to avoid duplicating in this document what is better stated in source code.  This should be a road map to the details of the source code, which focuses on emphasizing the essential and critical decisions and mechanisms.  Leave the details to the source code.  In fact, when low level details need to be conveyed in this document, it is best to use source code snippets or examples to make them clear. 

 

Architecture

The architecture should be depicted using a simple package diagram that identifies all the major components or modules of your system and the dependencies between them.

For each module or component, you need a clear definition of its purpose and the functionality it will provide. This includes any third party or commercial components. For example, if you are using Microsoft or Java, you need to indicate specifically what packages, classes and methods you are intending to use and why.

The API for each module must be clearly and explicitly defined. Pretend there is a programmer who knows nothing about the internals of your module (nor do they want to). They simply want to know how to use your module. So you need to tell them what classes and/or methods can be called and how they should be called.  It is acceptable and encouraged, to define your API by copying the source code “headers” (including comments) for your “public” classes that make up your API this should include the method signatures for all public methods of those classes.

Design

The design of your system needs to be described using diagrams (preferably UML). Usually a combination of class diagrams and interaction diagrams are used.  You do not need to document and diagram every single class in your system.  Show what is important for understanding the design of the system.  Only show important relationships, methods and attributes.  Leave the details to your source code.

Your design should show how your system will satisfy the most critical functional requirements.  This is done with interaction diagrams of the main participating classes for the most significant scenarios that relate to your use cases. The intent here is NOT to diagram every last step or method call in your system. The intent is to show how the different components and layers of your system distribute and coordinate the desired behavior. Only critical classes or method calls should be mentioned.  In addition to the interaction diagrams you should have a couple of key class diagrams (View of Participating Classes) that show the relationships between the key classes and the cardinalities of those relationships.

Key mechanisms (like error handling, or persistence)  should also be documented using interaction diagrams and a view of participating classes as well.  Only one example of each key mechanism needs to be documented.  This will serve as a template for developers to follow throughout the system.

Algorithm(s) and the main non-functional requirements that are critical to your system should be described as well within the context of the overall architecture and design of the system. 

If you have a user interface interface you might have a “class diagram” showing the different forms or pages and the dependencies between them.

If you have a database you should have a entity-relationship diagram or “class diagram” and a database schema (with comments)

Alpha System

Screen shots to illustrate the current progress of your system should be included in your status report for the iteration.

Project Plan

Now that the architecture and design has been completely specified, you should have a complete project plan that captures all the tasks left to do on your project (and who will do them). Ideally, it would be broken down so that no individual task is more than 1 week in duration.

Quality Assurance Report

Include a test report (of around 1 to 2 pages) that reflects the current state of your “alpha” system.  The report should provide a brief description of the release that was tested.  Clearly indicate what release was tested (date and/or build number) and indicate what requirements were supposed to be addressed in the release in terms of use cases and non-functional requirements.  Then summarize the tests that were run to verify your system.  For each test, you can indicate whether or not it has been implemented yet (i.e. can you run the test), and whether or not the system has passed the test.  You should also summarize the status of bugs.  How many, what severity, and what is the rate of change in finding and fixing bugs.