Design Document Template

You are to use this document as a template to prepare your design document.

Warning: There is a lot of flexibility in the way this document can be completed. We have discussed this flexibility in class. What that means is that you as a team are going to have to decide what information ultimately becomes part of your design document. The basic heuristic you should apply here is that the design document is to be used by the programming team to directly implement the prototype. Another high-level heuristic is to understand that the design document needs to:

be clear on how your system will be implemented, as opposed to the what it is supposed to do, which was the purpose of the requirements document;
define the component parts, their interfaces and how they interact. This involves both static (what pieces are there) and dynamic (how do they communicate/interact) information of your system; and
define how the system will look, or what the user interface appearance will be.

I recognize that some of the directions in this document will be vague. It is your job to do the best you can at providing a complete and clear design document. But in the event that you are bewildered about what to do, you should contact the TA or instructor. And you should get your design document, version 1 in on time in order to get feedback on how to correct it.

Use this template to complete your design document.

From the Project Milestones we have that a Design document is

A detailed description of how the system will be built, including, for example any object-oriented analysis and design to show the system structure.

-->Cut Here<--

[Project Name] Design Document

Spring Quarter 1996
1/29/96

Document Author:

Name of author

Project Sponsors:

Sushil Louis

[Project Name] Team:

Name (Manager)
Name (Architect)
Name (Programmer)
Name (Technical Writer)

Project Description of Target System

Copied from previous documents. In fact, you can just put in an explicit link, if you want, so that when you update the project description it automatically points to the most current version in all of your documents. The wonders of hypertext! :)

High-level architecture

If you had to describe your system to a technical manager and you had only one slide to do so, how would you describe it? Typically, this would involve a box-and-line diagram of the system, together with some prose stating something to the effect of, "The system is divided up into x major components, as depicted in the diagram." This high-level box-and-line diagram is what we will refer to as the overall architecture of the system and it represents a decomposition of the system into units, which we could call components, modules, or subsystems. The lines in the diagram suggest communication paths between the units, and those can be realized by procedure calls, socket communication, accessing of global data or read/writes to a file. In any event, there is some meaning associated to what goes on inside a box and some meaning for what a line connecting two units. It is that meaning which must be clear in your high-level decomposition. As an example, here is an architectural representation of the client-server organization of a vanilla-flavored WWW system: sample
architecture picture

Figure 1: Sample architecture drawing (WWW)

But the identification of the units in the architecture by means of a static box-and-line diagram is only one part of the picture. It is also important to have some information on the dynamic behavior of the system, or how the communication/connections work and when. One way to do this is to provide an interaction diagram that shows how the various components interact under normal usages (scenarios) over time.

In this section, I want you to provide a high-level decomposition of your architecture in the form of a box-and-line diagram accompanied by a natural language description of the dynamic behavior. A sample of the kind of description I am looking for is the following used to describe the architecture in Figure 1:

The Web is a distributed hypermedia system organized as a loosely connected set of clients and servers that share a common set of communication protocols and markup languages. Servers make Internet resources available to a community of clients that speak a common protocol. In addition, WWW clients typically understand a number of other protocols. Figure 1 depicts the WWW software architecture. In this example, we only consider the connection between a WWW client and WWW server, even though it is possible for a WWW client to natively speak to other IISs (Gopher, FTP, etc.).
WWW clients provide a User Interface Manager. This manager can be graphical or character based. The User Interface Manager captures user's request for information retrieval in the form of a Uniform Resource Locator (URL) and passes the information to the Access Manager. The Access Manager determines if the requested URL exists in cache and also interprets history-based navigation, e.g. `back'. If the file is cached, it is retrieved from the Cache Manager and passed to the Presentation Manager for display to either the User Interface or an external viewer. If the file is not cached, the Protocol Manager determines the type of request and invokes the appropriate protocol suite to service the request. This protocol is used by the client Stream Manager for communicating the request to the server. Once the client Stream Manager receives a response from the server in the form of a document, this information is passed to the Presentation Manager for appropriate display. The Presentation Manager consults a static View Control configuration file (mimerc, mailcap, etc.) that aids in the mapping of document types to external viewers.
Currently, the WWW servers available implement a subset of defined HTTP requests. This subset allows for: the retrieval of documents; the retrieval of document meta-information; and server-side program execution via the Common Gateway Interface (CGI).
When a request is received by the server Stream Manager, the type of request is determined and the path of the URL is resolved via the Path Resolver. The HTTP Server consults an Access List to determine if the requesting client is authorized to access the data pointed to by the URL. The HTTP Server might initiate a password authentication session with the client to permit access to secured data. Assuming authentication succeeds, the HTTP Server accesses the File System (which is outside the WWW Server boundary) and writes the requested information to stream. If a program is to be executed, a process is made available (either new or polled) through the CGI and the program is executed, with the output written by the server Stream Manager back to the WWW Client.

Design specification

Now, we need to break down the high-level architecture further to give more information on how the different units are realized. There are a number of options to pursue at this point. If you are doing a object-oriented development (e.g., all of the Java teams), then you should follow a standard OO development process, providing static object models, interaction diagrams and object templates, as you were taught in CS 2390. Ultimately, I want to see a collection of object classes defined, clearly indicating the attributes or member functions.

If you are not doing an object-oriented approach, then you can still further subdivide the units of your architecture from the previous section to describe various compilation units of your system. Each compilation unit will have a set of defined operations or procedures that it defines and provides as a programming interface to other units in the system. Each compilation unit should be clearly defined in terms of some design template which lists the name of the procedure, its arguments (and their types) and gives a brief description of what that procedure should do (pseudocode is fine).

For those doing Java implementations, find out about the javadoc utility to automatically create HTML documentation of Java classes.

User Interface

Most of the document up to this point has been concentrating on defining units and their interfaces. There is one particular interface that needs further description, the user interface. In this section, I want to see a detailed description of the actual user interface that is to be developed. This should be in the form of screen drawings that indicate how the system will appear. These can either be computer drawn in some graphics packages or they can actually be screen dumps from an early prototype of your system. Almost every system has a user interface, whether it is a window to control parameters of a network infrastructure or a Web interface to a mail browser. I want to see what the system is going to look like to the person who will be operating/using it.