Documenting an Architecture 10 pages, half pictures

Why Document? You can’t build it if it is unknown! History – to provide cyclic improvement Justification Analysis Decisions that were made

Is there a standard for Architecture Documentation?

Uses of the Documents Documentation should meet the needs of the stakeholders

Stakeholder “Qualities” What are the qualities or properties of a stakeholder. Experience – new or seasoned Novelty Prescriptive vs. Descriptive Future architect

Table 9.1 in text List of typical stakeholders and their main use(s) of the architecture It’s on page 204

Views Architecture can’t be displayed in a single view Complex Varied Many aspects No right set of views

Recall views from CH 2 Module views Component and Connector views Allocation views Architect needs to think in terms of: Structured set of implementation units Elements with runtime behavior Non-software structures in the Environment

How to choose what views to use What does the architecture consist of? What are the needs of the stakeholders? Build a stakeholder table – table 9.2 Make a list of possible views Combine views Prioritize

Documenting a View Primary presentation Element catalog Context diagram Variability guide Architecture background Consider a separate document for this Glossary Other See pp

Primary presentation Contains: Elements Relationships Possible methods Graphical Tables Plain old text

Elements Catalog Details Purpose Roles Behaviors Interfaces Text!

Context Relation of view to the rest of the architecture

Variability Guide Discussion of things not yet bound Guide to developers

Background Rationale Analysis results Assumptions

Other Management information Configuration control Change histories Requirements traceability

Behavior Dynamic aspects UML diagrams Other formal mechanisms Petri diagrams  Petri diagrams contrasted with activity diagrams Petri diagrams contrasted with activity diagrams RM-ODP

Interfaces Syntactic Signature – names, parameters, types Semantics Meaning Constraints

Element interface spec template in text Figure 9.2, p 215

Organization How is it laid out What is there Why it is this way

Helpful layout techniques View catalog Name Description of view elements Description of view purpose Management information View template

How to use UML Authors’ view is section 9.6, pp 218 – 229.