Documenting your Software Architecture

by Jim Alateras

It still surprises me that the practice of documenting software architectures is largely unpracticed in both the open source and commercial software projects. The act of documenting a software architecture lays a solid foundation for the project. Here are some reasons why you should consider practicing the unpracticed.

  1. The software architecture is a core project asset.
  2. The software architecture bridges the problem space and the solution space.
  3. The software architecture addresses the stakeholders concerns.
  4. The software architecture is the foundation to planning and risk mitigation for the project.
  5. 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


2006-03-20 22:10:42
how about some examples
hi there,

can you give some example(s) ?

that would help your reader know how you document it.

thank you,