Document architecture

By Destaye A.
 Contents
 Architectural Documentation
 Views
 Choosing the Relevant Views
 Produce a candidate view list
 Combine views
 Prioritize
 Documenting a View
 Parts of documenting a view
 Documenting Behaviour
 Documenting interface
 Template for documenting interfaces
 Documentation across Views
 Approaches to software architecture documentation
 Architectural Documentation
 An architecture produced by architectural design process mainly
produces diagrams
 Therefore, it must be described/documented in sufficient
detail, without ambiguity, and organized so that all
stakeholders can quickly find the information they need.
 Documentation depends on how software architecture will be used
 Abstract enough for new employees
 Detailed enough as analysis blueprint
 Specific for specific stakeholders - Security analysis,
implementers
 Benefits of architectural description are to serve as a
communication vehicle among stakeholders, construction
and evolution, reuse & analysis
 Views
 View is a representation of a coherent set of architectural
elements and relationships among them, as written by and read
by system stakeholders.
 There are many viewpoints for an architecture.
 Documenting the architecture is a matter of
 Documenting the relevant views
 Adding documentation that applies to more than one view
 Documenting architecture has the following parts
 Choosing the relevant views
 Documenting a view
 Documenting information that applies to more than one view
 Choosing the Relevant Views
 Architects need to think about their software in at least three
ways:
 How it is structured as a set of implementation units (module view)
 How it is structured as a set of elements that have runtime behavior and
interactions (component-and-connector view)
 How it relates to non-software structures in its environment (allocation
view)
 Different views
 Support different goals and users
 Highlight different elements and relationships
 Documentation package needed is based on
 Who the stakeholders are
 The future uses of documentation
 Quality attributes
 Choosing the Relevant Views…
 Approach to Choosing Views
 Produce a candidate view list
 Combine views
 Prioritize
 Produce candidate view list (matrix)
 build a stakeholder/view table
 List stakeholders and views
 Fill in amount of cell info: none, overview only, moderate, detail, high detail
 Combine views
 The above step may yield an impractically large number of views
 Remove views with “overview only” info or serve very few stakeholders.
 See if the stakeholders could be equally well served by another view
having a stronger constituency.
 Choosing the Relevant Views…
 Next, look for views that are good candidates to be combined
 that is, a view that gives information from two or more views at
once.

 Prioritize
 After combining views you should have an appropriate set of views
to serve your stakeholder community.
 At this point you need to decide what to do first – i.e. prioritize.
 How you decide depends on
 the details specific to your project,
 Interest – (some stakeholders' interests supersede others)
 Choosing the Relevant Views…

Stakeholders and the Architecture Documentation They Might Find Most Useful
Documenting a View
 Documenting a View…
1. Primary presentation
 Elements and relationships among them that populate the view
 Not necessarily all of them.
o Example, you may wish to show the elements and relations that
come into play during normal operation, but relegate error
handling or exceptional processing to the supporting
documentation.
 The primary presentation is usually graphical, sometimes tabular
2. Element catalog
 Details at least those elements and relations depicted in the primary
presentation, and perhaps others.
 Elements or relations omitted from the primary presentation are
introduced and explained.
 The behavior and interfaces of elements are two other aspects of an
element catalog
 Documenting a View…
3. Context diagram
 Shows how the system depicted in the view relates to its environment
in the vocabulary of the view
 Example: component-and-connector view
 Show which component and connectors interact with external
components and connectors
 Via which interfaces and protocols
4. Variability guide
 shows how to exercise any variation points that are a part of the
architecture shown in this view.
 Example , software product lines where the product line architecture is
suitable for multiple particular systems
 Includes documentation about each point of variation in architecture,
including the options among which the choice is to be made and the binding
time of the option
 Documenting a View…
5. Architecture background
 explains why the design reflected in the view came to be - Why it is as it is,
provides convincing argument that it is sound
 Includes
 Rationale: why decisions reflected in view were made and why alternatives
were rejected
 Analysis results: justifies design or explain what would have to change in case
of modification
 Assumptions reflected in the design
6. Glossary - terms used in the views, with a brief description of each.
7. Other information
 Contents of this section vary with the product and the organization
 May include
 Management information
 References to specific sections of a requirements document for traceability
 First part of the section must detail its specific contents
 Documenting behavior
 Structural information (views) not enough e.g. - deadlock not captured
 Behavior descriptions add information that reveals
 the ordering of interactions among the elements
 opportunities for concurrency
 time dependencies of interactions - at a specific time or after a period of time
 Behaviour can be documented about
 An element or ensemble of elements working in concert
 Exactly what to model will depend on the type of system being designed.
 For example, if it is
 a real-time embedded system, need to say a lot about timing
properties and the time of events.
 a banking system, the sequence of events (e.g., atomic transactions
and rollback procedures) is more important than the actual time of
events being considered.
 Documenting behavior…
 Different modeling techniques and notations are used depending
on the type of analysis to be performed.
 In UML, sequence diagrams and state charts are examples of
behavioral descriptions.
 State chart diagrams
 Formalism for reactive systems
 Reason about the whole system
 Abstraction and concurrency
 Sequence diagrams
 Document sequence of stimuli exchange
 Collaboration in terms of component instances and their interactions
 Time sequence shown
 Documenting interfaces
 An interface is a boundary across which two independent entities
meet and interact or communicate with each other.
 Interfaces are architectural - they carry the properties externally
visible to other elements. Suggested standard organization for interface
documentation.
 Template for documenting interfaces
1. Interface identity
 When an element has multiple interfaces identify the individual interfaces
to distinguish them and name them & provide a version number.
2. Resources provided
 Includes descriptions of Parameters, Preconditions, Post conditions
3. Data type definitions
 If interface resources employ non-standard data type, the architect needs
to communicate the definition of that type
4. Exception definition
 describe exceptions that can be raised by the resources on the interface
5. Variability provided by the interface
 Does the interface allow the element to be configured in some way?
 If so, document the configuration parameters and their effect on the
semantics of interface
 Template for documenting interfaces…
6. Quality attribute characteristics of the interface
 document the quality attribute characteristics the interface makes known
to the element's users.
 e.g. constraints on implementations of elements that will realize the
interface
7. Element requirements
 Specific, named resources provided by other elements : Syntax,
semantics, any usage restrictions
 Often convenient to document this info as a set of assumptions that the
element has made about the system
8. Rationale and design issues
 Architect needs to record the reasons for an element interface design
 Motivation behind design, constraints, compromises, alternative
designs, why the above rejected
9. Usage guide - Example of calling/using the element
 Documentation across Views
 It is about capturing the information that applies to more than
one view or to the documentation package as a whole.
 Cross-view documentation consists of just three major aspects
 How the documentation is laid out and organized, so that stakeholder
finds info efficiently and reliably
 View catalog and view template
 What the architecture is
 Short system overview informing about purpose of system, the way
views relate to each other; list of elements and where they appear;
project glossary
 Why the architecture is the way it is
 Context of the system, external constraints for the architecture shape,
rationale for coarse grained large-scale decisions
 Approaches to software architecture documentation
 Current Models
 Kruchten’s 4+1 view model
 Logical view, process view, development view, physical view and
scenarios
 Soni’s view
 SA as used in industrial applications.
 Rational Unified Process (RUP)
 Derived from Kruchten’s approach.
 IEEE 1471 standard
 A recommendation for SA documentation.
 Bass’s approach
 Project template given to you
 Kruchten’s and Soni’s approaches are foundational and have influence
on the others.
IEEE 1471 standard
Design an architecture

By: D.A.
 Design Strategy

 Decomposition
 Architecture determines quality attributes
 Important quality attributes are characteristics of the whole system.
 Design therefore begins with the whole system
 The whole system is decomposed into parts
 Each part may inherit all or part of the quality attribute requirements from the
whole
 Designing to Architecturally Significant Requirements
 Generate and Test
The Attribute-Driven Design Method

 An iterative method. At each iteration you:

 Choose a part of the system to design.
 Organize all the architecturally significant requirements for
that part.
 Generate and test a design for that part
 The Steps of ADD
1. Choose an element of the system to design.
2. Identify the ASRs for the chosen element.
• For whole system- use a utility tree
• For the element down the decomposition tree- generate a
utility tree from
 the requirements for that element.
3. Generate a design solution for the chosen element.
• Apply generate and test to the chosen element with its ASRs
 4. Inventory remaining requirements and select the input for
the next iteration.
 5. Repeat steps 1–4 until all the ASRs have been satisfied.