CISC 498 Information Technology Project
School of Computing		Design Document

Overview

The design document will have two parts as outlined below: external desin document and internal design document.

External Design Document

The purpose of an external design document is to communicate how the system will appear to its users, how it will interface with existing work processes, how it will interface with other pieces of software, and what kinds of work products are required by/produced by the system. The external design document is written from the perspective of a user. It does not specify how the system's features will be implemented.

Your external design should be created in cooperation with your customer. You should create low fidelity prototypes to help walk your customer through the design. External design is iterative; plan to revise and rethink in response to your customer's feedback.

External design helps to refine your understanding of requirements. Do not be surprised to find that your discussions of external design bring to light misunderstandings in the systems requirements, possibly requiring you to significantly rethink your design.

Structure

Your external design document should be about 20 pages in length, and should contain the following sections:

Introduction	Give a high-level description of the problem that your software is meant to solve.
User interface design	Describe the system from the point of view of its users. Use whatever descriptive techniques are best for describing your kind of system. E.g., use screenshots to describe the user interface's appearance; use state machine diagrams to describe the navigational structure of the application (particularly useful for web-based applications); use English text to describe the system's operation. It is not necessary at this point to have finalized the graphic design of your system, but the structural elements of the system should be pinned down.
Usage scenarios	Use scenarios to describe examples of how the system will be used. Scenarios should exemplify important usage cases. Use different scenarios to illustrate different user roles.
Prototype	Briefly describe the low-fidelity prototype you created. Give example screenshots/mockups (if different from the screenshots shown under user interface design.) Discuss your choice of prototyping technology (e.g., HTML, flash, pen and paper.)
Work products	Describe work products required by your system to operate (e.g.., any existing files that your system requires as input.) Describe work products your system produces (e.g., and files/documents that are created as a result of using the system. This helps characterize your system's boundaries.
Integration with existing processes	Describe how your system operates within the context of a broader process. This will demonstrate that your system effectively fits within the way your customer works.
Feedback from customer	Briefly discuss your customer's feedback on your external design. Briefly give examples of how the design changed as a result of your customer's input. Specify any concerns that may need to be addressed via further refinement.
Requirements update	Briefly specify any changes to the system's requirements that have come as a result of the external design process.

  

Internal Design Document

The purpose of a system's internal design document is to communicate to implementers how the system should be built. The internal design document should specify the system's architecture, deployment information, algorithms of note, special plans for addressing noteworthy quality requirements, and programming tools to be used.

Internal design is iterative; plan to revise and rethink aspects of your design as you work through implementation, and as you continue to work with your customer to refine your understanding of the system's requirements.

The contents of an internal design document are influenced by the kind of software being developed. A simple web application will typically have a less stringent level of document than that of a safety-critical system such as control code for a nuclear reactor or software controlling brakes in a car. You may adapt the following template as necessary to suit the software you are developing.

Structure

Your internal design document should be about 20 pages in length, and should contain the following sections:

Introduction	Remind the reader of the goals of your system, and give an overview of the structure and contents of the internal design document.
Programming environment	Detail the programming tools and languages that you will use to create the system. Specify, for example, your IDE, programming language(s), compilers (and versions), database system, source control system, UML tool, etc.
Software architecture	This will most likely be the largest section of the document. See details below.
Data design	If your system may interact with persistent data, for example, input/output files or a database, specify the format of this data. Useful ways of specifying your data might include BNF specification of data files, XML Schema specification of XML formats, and ER diagrams and relational schemas for databases.
API design	If your system provides an API to application programmers, provide a clear and detailed specification of the API.
Algorithms	Specify any complex algorithms used in your system. If the algorithm is standard, provide a reference to where the reader can learn about it. If the algorithm is non-standard, provide pseudo-code or other appropriate description.
Notable tradeoffs	You may have had to make design tradeoffs to meet the system's quality requirements (e.g., related to availability, security, performance, etc.) Discuss these tradeoffs, with specific reference to your system's design as discussed in the above sections.
Notable risks	Discuss any areas where you potentially risk failing to meet the system's requirements. Relate these risks to specific aspects of the internal design. Specify how you plan to address and ameliorate these risks.
Milestones	Update the milestones from your project plan.

Note in the above that different systems will place more or less emphasis on different parts. Some systems will provide no API, therefore will require no API specification. Other systems will have no complex algorithms to discuss. Other systems may have little or no persistent data. Adapt this structure to best suit your application.

Software Architecture

The description of your software architecture will consist of:

• Component and deployment view. This should identify the major components of the system, show how they are allocated to nodes, and establish the architecture's subsystem structure. I suggest using the "calls-perspective" notation from CISC 322, based on UML component and deployment diagrams.
• Class-based view. If appropriate, show the object-oriented design of parts of the system, using UML class diagrams and package views.
• Identify architectural styles and design patterns you have chosen to employ.
• Specify the interfaces of key components, specifying for each operation in the interface its input/output parameters, pre/post-conditions and exceptions.
• For all of the above, provide sufficient English-language text to explain your design.

In general, the goal of the architectural description is to be sufficiently detailed, precise and clear that a design team can use the document as the basis for implementation.