Documenting Software Architectures
1. Uses and Audiences for Architecture Documentation
• Architecture documentation serves as a means of education
• Architecture documentation servers as a primary vehicle for communication among
stakeholders
• Architecture documentation serves as the basis for system analysis and construction
2. Notations for Architecture Documentation
• Informal notations
• Semiformal notations (e.g. UML)
• Formal notations (e.g. Architecture Description Language (ADL))
3. Views
Documenting Software Architectures
Documenting Software Architectures
Properties of a module in module view
• Name
• Responsibility
• Visibility of interfaces
• Implementation information
• Mapping to source code units
• Test information
• Management information
• Implementation constraints
• Revision history
Documenting Software Architectures
Documenting Software Architectures
Properties of a component or connector in C&C view
• Name
• Type
• Reliability
• Performance
• Resource requirements
• Functionality
• Security
• Concurrency
• Modifiability (for data message)
• Tier
Documenting Software Architectures
Documenting Software Architectures
Documenting Software Architectures
Views
• Quality Views
For documenting how quality attribute requirements are fully realized in the architecture
design.
•
•
•
•
•
Security view
Communication view
Exception or error-handling view
Reliability view
Performance view
Documenting Software Architectures
4. Choosing the Views
•
•
•
Step 1: Build a stakeholder/view table
Step 2: Combine views
Step 3: Prioritize and stage (usually decomposition (module) view first)
5. Combining Views
•
•
The easiest way to merge views is to create an overlay that combines the information that would
otherwise have been in two separate views.
Common combinations:
• Various C&C views
• Deployment view with either SOA or communicating-processes views
• Decomposition view and any of work assignment, implementation, uses, or layered views
6. Building the Documentation Package
•
•
Documenting a view
Documenting information beyond views
7. Documenting Behavior (using trace-oriented languages)
Traces are sequences of activities or interactions that describe the system’s response to a specific
stimulus when the system is in a specific state. A trace describes a sequence of activities or
interactions between structural elements of a system.
• UML use case, sequence, communication, activity, state machine diagrams.
Documenting Software Architectures
Documenting Software Architectures
Documenting Software Architectures
Documenting Software Architectures
Documenting Behavior
• Documenting an architecture requires behavior documentation that complements structural
views by describing how architecture elements interact with each other.
• Two kinds of notations available documenting behavior
• Trace-oriented languages
• Traces are sequences of activities or interactions that describe the system’s response
to a specific stimulus when the system in a specific state.
• A trace describes a sequence of activities or interactions between structural elements
of a system.
• 4 notations of documenting traces:
• Use cases
• UML sequence diagram
• UML communication diagram
• UML activity diagram
• Comprehensive languages
• Architecture Analysis and Design Language (AADL): reason about runtime behavior
• Specification and Description Language (SDL): for telephony
Documenting Software Architectures
Documenting Software Architectures