This page gives the desription as to what is expected from the Design
Document .
The following diagrams can be referred to as examples :
1 . Architecture Diagram
DESIGN DOCUMENT
The requirement for the design document is as follows:
(1) Software architecture
A diagram showing the principal software components, modules or subsystems
in your proposed system and their relationships. The
components should collectively be responsible for all the behaviors
described in your requirements document. Relationships between
components are directed and mean that one component uses another to
do something. (E.g. the "TimeChooser" module may ask the "Calendar" module
to provide a set of available times.)
Show components as boxes and "uses" relationships (e.g. component A gets component B to do something for it) as arrows between the boxes.
[Why do this? -- Because the architecture diagram provides a big picture
of the internal structure or anatomy of your software system, its
components and how they interact.]
(2) Module/subsystem responsibilities
EACH component/subsystem in your architecture should be described in
a short paragraph. The description should show that the component has a
cohesive function or responsibility. (E.g. the responsibility of TimeChooser
in the above example might be to choose a time for a meeting
based on data about availability of invitees.)
There is no need to describe actors that fall outside the system (e.g. the user or externally developed systems with which yours interacts).
[Why do this? -- Because the names of components -- which are necessarily
limited to one or two words -- may not reveal precisely what
the components are responsible for.]
(3) Scenarios of use
Include TWO scenarios of use from your original requirements. Unlike
requirements scenarios, which are black-box scenarios with the system
appearing as a single entity interacting with its environment, your
design scenarios should split the system into the same components that
appear in your architecture diagram. Thus, if your design involves
a TimeChooser and a Calendar component, among others, your scenario should
show not only the interactions between the system's components and
the actors in the environment (e.g. users), but also interactions BETWEEN
system components (e.g. interactions between the TimeChooser and Calendar
modules during the execution of the scenario in question).
Scenarios should preferably be shown as sequence diagrams, in which
parallel vertical lines represent the time course of the components or
external actors that participate in the scenario (with time going down
the page), and oblique or horizontal arrows between the vertical lines
represent the occurrence of one component using another (e.g. the TimeChooser
actually asking the Calendar when the invitees are free.)
There is no need to elaborate usage occurrences with parameters, just
a phrase superimposed on the arrow's destination component is sufficient.
If you really insist, you may represent the scenarios either as tables
(as discussed in class and in the OBA paper by Rubin and Goldberg) or as
narrative texts. HOWEVER, you must include the information described
above: exactly what component does what and communicates with what other
components and when.
[Why do this? -- Because the architecture of a software system cannot
be evaluated on static grounds alone -- e.g. by inspecting an architecture
diagram. You don't really understand a software design until you understand
how the pieces work together as the system operates.]
(4) Rationale
No more than a page MAX that describes your thinking about the architecture
and other possible modular structures that you considered
and rejected. It is possible that your scenario analysis reveals problems
with your architecture that time doesn't permit you to fix. (It
would be best to fix them, though.) In that case, it is quite acceptable
to criticize your own architecture. Or perhaps your architecture may
seem a bit clunky with unnecessary indirection or redundancy, but you
envisage it evolving in the future with the injection of foreseen
requirements. Great. Say so.
[Why do this? -- Because a design is the result of a design process
that should involve discussion and evaluation, and I would like a summary
of
those deliberations to be public. A reasonable design that shows evidence
of having been thought about is better than a great design that
could have fallen from the sky.]
