SOFTENG 325 Lecture 30:Software Architecture Documenting Architecture 1 Rainbow Yuhong Cai email: yc

1
SOFTENG 325 Lecture 30Software
ArchitectureDocumenting Architecture
(1)Rainbow Yuhong Caiemail
ycai003_at_cs.auckland.ac.nzoffice hour 4pm 5pm
Wednesday 4pm5pm Friday
2
Theme of the two lectures

• How to document model software architectures?
• Uses of Architectural Documentation
• General guidelines for documentation
• Rational/UML approach using views

3
CONTENTS

• Uses of Architectural Documentation
• Guidelines for Documentation
• Views
• Choosing the Relevant Views
• Documenting a View
• Documentation across Views

4
Uses of Architectural Documentation

• Architecture documentation is both prescriptive
  and descriptive
• For some audiences it prescribes what should be
  true by placing constraints on decisions to be
  made. For other audiences it describes what is
  true by recounting decisions already made about a
  systems design.
• Document mainly works as a communication vehicle
  among stakeholders.
• Document can work as a training vehicle.
• Document provides base for system analysis.

5
Documentation Guidelines

• Documentation should be written from the
  perspective of the reader
• organize for ease of reading / reference
• mark to be determined/ left blank rather
  than leave open
• Avoid Repetition
• much easier to maintain (avoid inconsistency)
• e.g. reference other sections/documents rather
  than copying
• Avoid Ambiguity
• use legenda/key with diagrams
• supplement diagrams with natural language

6
Documentation Guidelines (Contd)

• Use a standard organization of the document
• in organizations with many projects
• Record Rationale
• these form part of guidelines for evolution
• helps delegate design decisions
• Keep it current
• Review for fitness of purpose
• have (future) users test the documentation

7
Views

• Structure vs. Architectural View
• The structure or structures of the system
  comprise elements, the externally visible
  properties of those elements, and the
  relationships among them.
• A view is a representation of a coherent set of
  architectural elements, as written by and read by
  system stakeholders. A structure is the set of
  elements itself, as they exist in software or
  hardware.
• Architectural View vs. documentation
• Documenting an architecture is a matter of
  documenting the relevant views and then adding
  documentation that applies to more than one view.
• Three parts in documenting architecture
• Choosing the relevant views
• Documenting a view
• Documenting information that applies to more than
  one view

8
Choosing the Relevant Views

• A simple three-step procedure for choosing
  relevant views for the intended project
• Produce a candidate view list
• Begin by building a stakeholder/view table, like
  table 30.1 for the intended project. For the
  columns, enumerate the views that apply to the
  intended system. Some views (such as
  decomposition or uses) apply to every system,
  while others only apply to systems designed that
  way. Once you have the rows and columns defined,
  fill in each cell to describe how much
  information the stakeholder requires from the
  view none, overview only, moderate detail, or
  high detail.

9
Table 30.1. A candidate view list
10
Choosing the Relevant Views (contd)

• Combine views
• The candidate view list from step 1 is likely to
  yield an impractically large number of views. So,
  you need to reduce the redundant views. For
  example, in small and medium projects, the
  implementation view is often easily overlaid with
  the module decomposition view, the module
  decomposition view also pairs well with uses or
  layered views, etc
• Prioritize
• Once a list of views are selected, you need to
  prioritize what to do first. How you decide
  depends on the details specific to your project,
  but remember that you dont have to complete one
  view before starting another.

11
Documenting a View

• An empirical seven-part standard organization to
  document a view
• Primary presentation shows the elements and the
  relationships among them that populate the view.
• Element catalog details at least those elements
  and relations depicted in the primary
  presentation, and perhaps others.
• Context diagram shows how the system depicted in
  the view relates to its environment in the
  vocabulary of the view.
• Variability guide shows how to exercise any
  variation points that are a part of the
  architecture shown in this view.
• Architecture background explains why the design
  reflected in the view came to be.
• Glossary of terms used in the views, with a brief
  description of each.
• The contents of additional information will vary
  according to the standard practices of your
  organization. They might include management
  information such as authorship, configuration
  control data, and change histories.

12
Documentation across Views

• Cross-view documentation consists of just three
  major aspects
• How the documentation is laid out and organized
  so that a stakeholder of the architecture can
  find the information he or she needs efficiently
  and reliably.
• What the architecture is. Here, the information
  that remains to be captured beyond the views
  themselves is a short system overview to ground
  any reader as to the purpose of the system.
• Why the architecture is the way it is the
  context for the system, external constraints that
  have been imposed to shape the architecture in
  certain ways, and the rationale for
  coarse-grained large-scale decisions.

13
Acknowledgement

• This lecture is based on book ltltSoftware
  Architecture in Practicegtgt written by Len Bass,
  Paul Clements, and Rick Kazman
• Also, part of contents is based on Documenting
  Architectures Architecture Description
  Languages written by M.R.V. Chaudron