Documenting your Software Architecture
by Jim Alateras
- The software architecture is a core project asset.
- The software architecture bridges the problem space and the solution space.
- The software architecture addresses the stakeholders concerns.
- The software architecture is the foundation to planning and risk mitigation for the project.
- The architecture document is a conceptual model of the solution.
A good architecture document addresses the concerns of the stakeholders and provides a context for the planning construction and testing effort. Many projects have failed because of the lack of architectural vision or the ability identify the architectural risks. Some develop an architecture document at the start of the project and put it away never to be seen. Instead it is a dynamic document that must be maintained throughout the product's life cycle. So if you are putting together an architecture document look for tools to help maintain it. Sometimes that may be as simple as a good word processor but in other cases it may be a modeling tool with the ability to automatically generation the documentation.
Some organizations produce huge architecture documents for large systems, which are incomprehensible, inconsistent and largely irrelevant and these are organizations that are rolling out huge mission critical applications. On the subject of writing architecture documents I adopt the 'views' approach proposed by people like Philippe Kruchen, and Paul Clements and organizations such as IEEE.
Here are some links
- Architectural Blueprints - The 4+1 View Model of Software Architecture
- The Tao of the Software Architect
- Documenting Software Architectures: Views and Beyond
- Software Systems Architecture: Working with Stakeholders Using Viewpoints and Perspectives
- IEEE Std 1471-2000 IEEE Recommended Practice for Architectural Description of Software-Intensive Systems
how about some examples