1

CS 446 - Tutorial 5Frid. Oct 23, 2009

Design Document Tutorial

2

Goals

This document along with the architecture document go hand in hand They are on different levels of looking at the system Shouldn’t repeat too much from before

However, it should be a standalone document Shouldn’t need the Architecture Document to

understand everything

3

Title Page

Title About 3-6 words highlighting the purpose of the document If you gave your system a name, use it again

Group Members Names, Student Ids

Group Number Date Submitted Try to stay consistent from before

4

Abstract/Executive Summary

About ½ a page highlighting the key points of the report

Aimed towards upper management usually Will not be bothered with the intricate design details Wants to know what’s important and why

Should describe what the project is about, and what this document will present.

Try to keep the abstract short and to the point.

5

Introduction and Overview

Introduce your system Say what it does (clear and concise description) State any assumption you have made about the

knowledge level of the audience.

Give an Overview of what is in your report

Highlight the headings of your report Give the key focus of each heading and explain the

breakup into subheadings Do not exceed a sentence or two description about each

section in your report.

6

Design For each module in your architecture, give a detailed specification

so that it could be implemented by a junior programmer

Behavior should be clearly described

Include a description of essential algorithms and data structures used

Can include pseudo-code for non-obvious parts of the implementation

Can include the ER diagram to describe your DB schema.

7

More on Design

Start thinking in terms of code

Modules will be a collection of code files

Need to discover a mapping between system modules and code files Each module is a package? Hierarchical Packages? No Packages at all? (Probably not a good idea!)

8

Diagrams

Diagrams are a good way to convey design information

BUT, choose your diagrams carefully! Don’t use a diagram unless it adds useful information for

the reader

Same Diagram rules apply as before Use any standard diagram or make your own Include a legend Always include explanatory text

9

More on Diagrams

Possible Diagrams to use: UML Component Diagram to show sub-modules UML Deployment Diagram UML Class Diagrams UML Scenario Diagram/ UML Sequence Diagram …

Not all of these are required! Use only what you think is necessary

UML Class Diagram

Class diagram

shows the different

classes in your

implementation

and how they

relate to each

other.

10

UML Deployment Diagram

Deployment

diagram

provides a

physical

look at the

system.

11

UML Sequence Diagram

Shows the interaction between objects in the order in which they occur.

12

13

Final Thoughts on Design

Remember the purpose of the document Jr. Programmer given nothing other than your document

could implement your system

Don’t get diagram crazy I want to see your design clearly presented I don’t just want to look at diagrams and have to wonder

what your doing

Reference Architecture document for critical data structures, abstractions and algorithms if needed

14

External Interfaces

More detailed than last time

Now need details about information going to/from the system Messages Protocols Database Structure Structure of Data Files GUI Mockups

Don’t need to reference/talk about feasibility studies

15

Data Dictionary

Data Dictionary Include a glossary that briefly defines all the key terms

used in your architecture

Can use the architecture document glossary as a base and update it for new terms

16

Programming Conventions

List all programming conventions/styles that will be used in your system

For example, if necessary, include: Variable Naming schemes Class naming schemes Role and Location of static variables/constants Etc…

17

References

References If you used anything to help you write your report, put it

here and cite it in the document Should have a reference to your architecture document Include any references that explain some of the

technologies you are using

18

General “Do” Tips

Use lots of headings and subheadings Label all diagrams and tables Feel free to include a Table of Contents, List of Figures,

List of Tables Will not count towards your page limit

Write clearly Include diagram legends Consider your prototype implementation while describing

the design Reference your architecture document where needed

19

General “Don’t” Tips

Do not exceed the 20 page limit

Don’t cram stuff into an appendix because it won’t fit

Be smart about what you include Useful diagrams

20

Keep in Mind

For the implementation, you are going to map what you describe to actual code.

The specification you write for each module or package here will be reflected as documentation in your code.

Make sure your design makes sense so you can implement it.

Keep it Simple!

21

Next week…

No tutorial next week Study for the midterm! The design document is due on Friday Oct. 30th

by 3 pm. Email me a soft copy Drop a hard copy in my mailbox in the Grad Student

Mailroom