Architecture Document Tutorial - CS 446 - Tutorial 2

jetmorebrisketSoftware and s/w Development

Aug 15, 2012 (5 years and 4 days ago)

247 views

1

CS 446
-

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!