For Layered Systems

Structure
The design document structure used for assignments 1 and 2 constitute a reasonable
starting point if you are developing a design document for a 3 layered business system:

Table of Contents

Revision History 2
1. Introduction 4
2. Requirements 5
3. Architecture 6
4. Database / Data Access Design 7
5. GUI Design 9
6. Class Diagram 11
7. Sequence Diagrams 12
8. Test Plan 15
Acknowledgements 16
 If you don’t like this structure, then there
are a wide choice of templates on the web,
but the structure (at least of the ones that I
have looked at) is essentially the same.
 This is hardly surprising, as the objective of
a design document is to enable a
development team to implement the
design, and all of the headings listed in the
TOC are things that a developer needs to
know about.
Content
 The sections need to be populated with appropriate
diagrams and content. Diagrams need to be
appropriate for the sections e.g.
○ ERDs for data models,
○ screen shots for the GUI design (GUI Builders are good
value here)
○ Bespoke diagrams for architecture
 Elsewhere, use UML diagrams as appropriate,
although note that I use screen shots to designate
package structure.
 Ensure that all UML diagrams are consistent, e.g. all
objects that appear in sequence diagrams must be
instances of classes that appear in the class diagram
 The class diagram includes all classes for all layers,
including interfaces. If it is too large for convenient
display, breaking it into separate layer diagrams is
fine.
 If the GUI has multiple screens (windows, cards,
panes, etc) show these individually as screen shots
and explain how each is activated / deactivated. For
complicated interaction schemes, a state diagram
can be useful, although you should consider
remodelling the GUI, as in the Case Study 1 GUI.
 The way that I employ sequence diagrams is that for
simple applications, each user requirement specified
as a use case has a corresponding sequence
diagram. Use cases are specified in overview form,
using a UML sequence diagram and each use case
is specified textually as a sequence of steps using a
template such as ….
 Generally speaking, there should be no
production code in the document. An
exception here is SQL queries.
 However, you may need to provide
specific processing logic – e.g. business
rules that apply for particular situations
or for Case Study 2, game logic. There
are UML diagrams that can be used for
this purpose, but often pseudocode is
more convenient.
 Don’t forget to add supporting text – the
document should read as story
 Supporting text needs be directly relevant
to the task at hand (implementation), so
don’t waffle. You can generally assume that
the target audience is familiar with the
basics of software design, architectural
styles and design patterns
 Remember that the purpose of the document
is to enable a separate development team to
implement your design.So read the final
document from the viewpoint an implementer,
or better, get someone else to read it from that
perspective.
 Note that there is a trade off here:
 Less detail in the design document means that you
will be more frequently pestered by the
implementers
 More detail means that you have done more work
than you have needed to
 Clearly, the balance point will depend on the
complexity of the application and the skills of
the development team