1. Documenting SW Architecture
Ran Levy

2. Why documenting the architecture?
Content
Why documenting the architecture?
How to document the architecture?
Preserving quality attributes using architecture document.
Summary

3. Why Documenting the Architecture?
Architecture is what makes the sets of parts work together as a successful whole;
architecture documentation
is what tells developers how to make it so.

4. Why documenting the architecture?
Education.
Basis for architecture analysis.
Manifests the earliest set of decisions:
Constraints on implementation.
Dictates organizational structure.
Supports SW maintainability:
Understanding effect of changes.

5. Why Documenting the Architecture?
Communication vehicle between stakeholders.
Self
SW Arch Document
Requirements Eng.
Managers
Testers
Designers & Architects
Implementors

6. Content
Why documenting the architecture?
How to document the architecture?
Preserving quality attributes using architecture document.
Summary

7. Documenting the Arch - Preface
You are NOT DONE when the document is done….

8. Documenting the Arch – The 7 Rules
Documentation should be written from the point of view of the reader, not the writer.
Avoid unnecessary repetition.
Avoid ambiguity.
Use a standard organization.

9. Documenting the Arch – The 7 Rules Con’t
Record rationale (and considered alternatives).
Important for tracking and remembering decisions.
Prevents endless re-discussions about alternatives.
Keep documentation current but not too current.
Early review of the documentation.

10. Documenting the Arch
IEEE Recommended Practice for Architectural Description of Architectural Description of Software-Intensive Systems.
“A Template for Documenting Software and Firmware Architectures” - HP, 2000.

11. Documenting the Arch – Views
Key Point: Different stakeholders have different needs.
Perhaps the most important concept associated with software architecture documentation is that of the view.

12. Documenting the Arch – Views
Philippe Kruchten – “4+1” approach to architecture documentation:
Logical view
Process view
Development view
Physical/Deployment view
Plus 1: binds all views together
its end users. Designers decompose the system into a set of key abstractions, taken mainly from the
problem domain. These abstractions are objects or object classes that exploit the principles of abstraction,
encapsulation, and inheritance. In addition to aiding functional analysis, decomposition identifies
mechanisms and design elements that are common across the system.
• The process view addresses concurrency and distribution, system integrity, and fault-tolerance. The
process view also specifies which thread of control executes each operation of each class identified in
the logical view. The process view can be seen as a set of independently executing logical networks of
communicating programs (“processes”) that are distributed across a set of hardware resources, which
in turn are connected by a bus or local area network or wide area network.
• The development view focuses on the organization of the actual software modules in the software-development
environment. The units of this view are small chunks of software—program libraries or subsystems—
that can be developed by one or more developers. The development view supports the
allocation of requirements and work to teams, and supports cost evaluation, planning, monitoring of
project progress, and reasoning about software reuse, portability, and security.
• The physical view takes into account the system's requirements such as system availability, reliability
(fault-tolerance), performance (throughput), and scalability. This view maps the various elements identified
in the logical, process, and development views—networks, processes, tasks, and objects—onto
the processing nodes.

13. Documenting the Arch – Logical View
Primarily supports the functional requirements - what the system should provide in terms of services to its users.
Designers decompose the system into a set of key abstractions – objects and relationships between them.
In addition to aiding functional analysis, decomposition identifies mechanisms and design elements that are common across the system.

14. Documenting the Arch – Logical View
Logical view is expressed by:
Architecture styles (e.g. Layered, MVC, …)
Components and interfaces description: CRC-R cards
Object, class, package and components diagrams.
For each section document the rationale:
Why this architecture style was chosen?
Why this component is not allowed to interact others?
Why the interface is based on messages? …

15. Documenting the Arch – Logical View
Example – CRC-R card
Component
Management I/F
Responsibilities
Provide support for management operations via SNMP and CLI. It provides Management Agents functionality together with unified management FW for allowing general way of accessing specific Network Services components.
Provided Interfaces
Configure node.
Monitor node's configuration.
Get node's statuses and statistics.
Perform node's maintenance operations.
Notify NE events to be delegated to the operator.
Get response from NS on required operation.
Rationale
Management I/F components allow access of the operator to the NE for management operations. Unified Management FW allows single interface usage for accessing Network Service that will serve all Management Interfaces and allow extension to additional interfaces in the future.
Collaborators
Network Services
Platform Services Components
Operator
Notes
Quality Attributes
Usability:
Management I/F should be user friendly, include guideline/help during each operation and provide the ability to configure and to display the full relevant and mandatory values in one command.
Management interfaces should allow range configurations.
Portability:
Separation of Management I/F from the NS via Management FW.
Issues
All supported Management Interfaces should be passed through Management FW, which allow single management interface for a Network Service which does not depend on type of the called management interface and should not be changed in case when additional management interface is added.

16. Documenting the Arch – Process View
Maps logical view into execution unit.
Takes into account quality attributes such as performance and availability.
Addresses concurrency and distribution, system integrity, and fault-tolerance.
Expressed by:
Class diagrams (using thread and process annotations).
Sequence Diagrams
Communication Diagrams
Activity Diagrams
Timing Diagrams
Interaction Overview Diagrams

17. Documenting the Arch – Process View
Examples

18. Documenting the Arch – Development View
Focuses on the organization of the actual software modules in the software-development environment.
Help managers in work assignments and teams establishment.
Expressed by:
Components diagrams.
Implementation mapping description.

19. Documenting the Arch – Development View
Example
Implementation Rules:
For each logical component a directory is created that contains all code files belonging to that
Header files should be places under pub directory.
Implementation files under src directory.
For each class (except inner class) a separate file is created.

20. Documenting the Arch – Physical/Deployment View
Maps the various elements identified in the logical, process, and development views—networks, processes, tasks, and objects—onto the processing nodes.
Focuses on distribution, communication and provisioning.
Accommodates quality attributes such as availability, reliability, performance, throughput and scalability.
Expressed by deployment diagrams.

21. Documenting the Arch – Physical/Deployment View
Examples

22. Documenting the Arch – Scenarios
This view represents the scenarios that tie the four views together.
The scenarios describe sequences of interactions between objects, and between processes. They are used to identify architectural elements and to illustrate and validate the architecture design.
They also serve as a starting point for tests of an architecture prototype.
Expressed by use cases diagram.

23. Documenting the Arch – Scenarios
Important scenarios to document:
Init & upgrade.
Scale up and down.
Handling events with hard deadlines.
Fault handling.

24. Documenting the Arch – Scenarios
Example –
System Initialization

25. Preserving quality attributes using architecture document.
Content
Why documenting the architecture?
How to document the architecture?
Preserving quality attributes using architecture document.
Summary

26. Preserving Quality Attributes
Be explicit In ALL relevant sections.
Quality attributes requirements section:
List all relevant attributes, detail them and specify how the architecture support each one.
Availability:
System shall support % up time.
No data plane affect due to system failures. …
The architecture of the system supports security by the following means:
Hitless upgrade
Support for specific module replacement without downtime.

27. Preserving Quality Attributes
Logical View:
Define the “rules” of the used architecture style.
E.g.: Strict layered architecture to support maintainability, extensibility.
Add to the CRC-R card quality attributes.
E.g.: Logger component must not exceed 5% of CPU consumption.
Document collaborators

28. Preserving Quality Attributes
Process View:
Add constraints to diagrams
Time constraints, components that must be used as part of the sequence (e.g. Authentication), parallel execution…
Use timing diagrams when needed.

29. Preserving Quality Attributes
Scenarios:
Documenting scenarios are a major key for many quality attributes.
Do NOT skip this section:
Upgrade Flow – supports availability and maintainability.
Fault Management flows – supports availability, fault localization, security.
Events handling flows – supports performance, scalability.

30. Content
Why documenting the architecture?
How to document the architecture?
Preserving quality attributes using architecture document.
Summary

31. Summary
Documenting the architecture is very important as mean for communicating the architecture and translating the architects ideas into practice.
Architecture documentation must be described by several views, that all together provides the complete view of the architecture.
The architecture document is major key for preserving the quality attributes of the system.

32. References
“Software Architecture in Practice”, Bass, Clements and Kazman, Addison Wesley, 2003.
“Documenting Software Architectures”, Clements, Bachman, et al., Addison Wesley, 2001.
“A Template for Documenting Software and Firmware
Architectures”, Ogush, Coleman et al., Hewlett-Packard Product Generation Solutions, 2000.
Wikipedia
“Software Architecture - Why what and how”, Alexander Katz.

33. Thank You