1 CS Tutorial 5 Frid. 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  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  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. 30 th by 3 pm.  me a soft copy  Drop a hard copy in my mailbox in the Grad Student Mailroom