1 CS Tutorial 2 Architecture Document Tutorial

2 Goals Get you comfortable with the architecture document deliverable Go over the assignment requirements Answer any preliminary questions you have on the deliverable

3 Goal of the Deliverable You are to produce a (web-readable) report that documents the architecture of the software that you propose to develop for your system (for its upper level)  Web readable = pdf, ps, etc. Document should not exceed 20 pages! Your target audience is a manager or developer who is somewhat but not intimately familiar with the technologies you might be using or with software architecture.

4 Title Page Title  About 3-6 words highlighting the purpose of the document  Feel free to give your system a name! Group Members  Names, Student Ids Course Number & Instructor Date Submitted

5 Abstract/Executive Summary About 1/2 - 2/3 of a page highlighting the key points of the report Usually aimed towards a manager or a developer Think Prof. Holt

6 Introduction and Overview Should be an introduction to your system  Say what it does  Do not use vague words when describing the functionalities of your system  State any assumption you’ve made about the knowledge level of the audience (but don’t deviate from the deliverable requirements!!!) Give an Overview of what’s in your report  Highlight the headings of your report  Give the key focus of each heading

7 Architecture Give the overall structure of the system  Major components and interactions Can be subsystems, packages, modules Also include threads, processes, DBs and data files  Focus on goals, maintainability, testability, etc. Do not focus on classes, variables, etc.  Focus on interactions BETWEEN components Do not focus on interactions WITHIN components

8 Architecture - Tips Relate architecture to Garlan and Shaw Styles Do not over complicate your design  System should be easy to understand with simple interfaces between components

9 Architecture - Diagrams Diagrams can be helpful in conveying your ideas  Diagrams alone are pretty useless  Always include some text explaining your diagram and do not forget to include a legend!  Can use UML if you want, or any other representation but sure to clearly explain your notation if you are using your own representation.

10 Architecture - Final Thoughts There are tools to help with the Diagrams  Microsoft Visio  Netbeans UML plugin (free) Don’t get too low level  But, include any abstractions or utilities that you will use

11 Use Cases Describe three use cases of the system  The choice is yours  Show how the use case interacts with the major components of the system Use any notation you like  Not necessarily UML, but something understandable.  Number your arrows (it makes things easier to trace).  Can include a description for each use case.

12 Use Cases – Example Description Name: Viewing Semester’s Schedule Use Case Number: UC2 Event: Student clicks on “View Schedule” after selecting a specific semester. System: Quest Actors: Student Expected Result: Schedule for specified semester is displayed. Overview: This use case captures the ability to produce the course schedule of a specific semester on request.

13 Data Dictionary and Naming Conventions Data Dictionary  Include a glossary that briefly defines all the key terms used in your architecture Naming Conventions  Explain all abbreviations and naming schemes The point is that your reader shouldn’t be lost in trying to figure out what you mean.

14 Tentative Test Plan Briefly describe how you will test your system  Automated or manual testing?  Unit/System Tests How will you test the entire system? Which scenarios will be tested? Any tools you will use in the testing process? Don’t exceed a page describing your test plan.

15 Methodology and Cost How will your system be built  In what order?  By whom (will each team member be responsible for a specific module)?  What’s the time estimate? Can use a Gantt Chart (can be done using MS Project) if you want A page or two in length

16 Performance and Evolvibility Performance  What areas could bottleneck your system?  How will you mediate them?  1/4 page Evolvability  How susceptible is your architecture to change?  Give an example  About ½ - 1 page

17 Feasibility Study and References Feasibility Study  How is your support software (DB, GUI frameworks) going to work with your system  Describe any prototype you might have done to test compatibility  1-2 pages References  If you used anything to help you write your report put it here and cite it in the document

18 General “Do” Tips Use lots of heading 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  Use simple language  Don’t be overly wordy  Include diagram legends

19 General “Don’t” Tips Don’t exceed the page limit  I won’t read any extra pages Don’t cram stuff into an appendix because it won’t fit  Appendices will count towards the page limit  Be picky in deciding what information is relevant and what isn’t

20 Next week… Come to the tutorial with questions about your document!