Software Architecture - 5
Effectively Documenting Software Architectures
Introduction
Proper documentation is essential for the effective communication, evolution and maintenance of a system's architecture.
Importance of software architecture documentation
Software architecture documentation helps:
Communicate the design to stakeholders like developers, testers and project managers.
Explain the rationale behind key architectural decisions and trade-offs made.
Provide a reference for developers during implementation and for maintainers later on.
Without documentation, much of the architectural knowledge resides only in the minds of the original designers and is lost over time.
Principles of Good Documentation
Some principles for effective architecture documentation:
Consistency: Use a standard template and terminology.
Clarity: Explain complex concepts simply and concisely.
Completeness: Cover all significant architectural elements and design decisions.
Conciseness: Avoid unnecessary details.
Accuracy: Validate the documentation against the actual system.
The seven-part documentation template
A recommended template includes:
Introduction: Scope, audience and constraints
Architectural Goals and Constraints
Architectural Decisions: Key decisions, trade-offs and rationales
Use Case Realization: Mapping of use cases to architecture
Architectural Viewpoints: Logical, process, deployment, physical views
Design Rationale: Reasons behind architectural choices
Future Work: Planned enhancements
This template covers key areas needed to properly document a system's architecture.
Principles of Sound Documentation
For architecture documentation to be effective, it should follow some key principles:
Completeness
The documentation should cover all significant architectural elements and design decisions. Nothing important should be left out. This ensures stakeholders have a full understanding of the system.
Consistency
A standard template and terminology should be used throughout the documentation. This makes it easier for readers to understand and navigate. Consistency also helps enforce best practices.
Correctness
The documentation should accurately represent the actual system design and implementation. It should be validated against the code to ensure no discrepancies exist.
Conciseness
The documentation should avoid unnecessary details that do not contribute to understanding the essential architecture. Only including relevant information keeps the documentation succinct and readable.
Clarity
Complex concepts should be explained simply and straightforwardly. Jargon and technical abbreviations should be defined. Visual aids like diagrams can improve clarity.
Context and Refinement
Context diagrams and refinement are techniques used to model and document a system's architecture at different levels of abstraction.
Context Diagrams
Context diagrams show the system at its highest level of abstraction, focusing on its interaction with external entities. They consist of:
The system boundary represents the system as a whole
External entities that interact with the system
Data flows between the system and entities
Context diagrams provide a high-level view of the system's inputs, outputs and interfaces, abstracting away internal details. They are useful early in the design process.
Refinement Process
Refinement involves breaking down the system into lower-level subsystems and components through iterative decomposition.
The steps:
Start with the context diagram, showing the system as a whole.
Identify major subsystems within the system boundary.
Create context diagrams for each subsystem, showing its external entities and data flows.
Continue decomposing subsystems into components and refining their context diagrams.
Iterate until reaching an implementable level of detail.
This top-down refinement process progresses from abstract to concrete, revealing increasingly more details about the architecture.
Documenting Variability
Variability refers to the ability of a system to be configured or customized for different purposes. It is important to document a system's variable aspects and variants.
Sources of Variability
Variability can arise from:
Optional features: Some features may be included or excluded
Platform dependencies: The system may run on different OSs, databases, etc.
Design alternatives: There may be multiple ways to implement a component
Extensibility: The system is designed to accommodate future extensions
Understanding sources of variability helps determine how the system can be configured.
Documenting Variants
Ways to document variants:
Feature models: Show features as a tree with variants as branches
Variability mapping tables: List features and their variants
Variability-aware diagrams: Annotate diagrams to show variants
For each variant:
Name the variant
Describe its purpose and constraints
Specify default and alternative configurations
Detail how variants are implemented
This documentation helps stakeholders:
Understand the system's configurable aspects
Select appropriate variants for their needs
Implement and test variants correctly
Software Interfaces
Interfaces define the points of interaction between software components. They must be well-documented for components to be developed and integrated successfully.
Types of Interfaces
Main types of interfaces:
API: Application Programming Interface defines functions, classes, etc. for use by other code.
GUI: Graphical User Interface defines how users interact with the software visually.
Network: Defines the protocol and message format for network communication.
Data: Specifies the data structures and file formats used to exchange data.
Hardware: Defines the electrical and mechanical specifications for connecting hardware devices.
Documenting Interfaces
Interfaces should be documented with:
Interface name and ID
Description of purpose and functionality
List of inputs, outputs, events and method calls
Data types and structures used
Error and exception conditions
Usage examples and code samples
This documentation enables:
Component developers to integrate correctly with interfaces
Testers to verify interface compliance
Maintainers to modify interface implementations over time
Documenting Behavior
Documenting how a system behaves and responds to inputs is an important part of architecture documentation.
Use Cases
Use cases describe interactions between the system and external actors, focusing on system functions or tasks. They:
Use actor/system names and simple verbs
Include basic and alternative scenarios
Specify pre/post conditions and exceptions
Use cases capture high-level functional requirements at an early stage.
Sequence Diagrams
Sequence diagrams show object interactions arranged in time sequence. They:
Show lifelines for objects and actors
Use messages to represent interactions
Indicate iteration and conditionals
They clarify the flow of control between components at a low level of detail.
State Charts
State charts represent component behaviour as state transitions triggered by events. They:
Define states using names and descriptions
Specify transitions between states triggered by events
Include actions performed on transitions or within states
State charts model the reactive, event-driven aspects of a component's behaviour.
Consistency with Design
Behavioural documentation should be:
Consistent with architecture and design models
Updated when designs change
Used to validate designs against requirements
This ensures the final implementation behaves as intended.
The Seven-Part Template
1. Purpose
Outline the business and system goals the architecture aims to fulfil. This provides context for stakeholders.
2. Context
Describe the system's operational environment and constraints. This helps assess architectural fitness.
3. Views
Present multiple views of the architecture using models and diagrams. Views show structural, behavioural and other aspects.
4. Variability
Document the system's configurable and variable aspects, variants and variation points. This ensures flexibility.
5. Rationale
Explain the reasons and trade-offs behind architectural choices. This justifies the chosen design and supports future evolution.
6. Reference Materials
List standards, technologies, components and other artefacts used. This provides a knowledge base for teams.
7. Open Issues
Detail known risks, limitations and areas for improvement. This helps focus future development efforts.
Using this template ensures architecture documentation is:
Complete: Covers key aspects like purpose, context, views, variability, rationale, etc.
Structured: Follows a consistent organization that is easy to navigate
Informative: Provides information needed by stakeholders to understand and use the architecture effectively.