Over the years I’ve helped many teams improve the way they architect their solutions. One topic that always comes up is how an architecture should be documented (especially in an agile environment). We quickly get into a discussion of the differences between models and views. In essence:
- A model contains the elements that comprise that model. For example, a data model will contain entities and the relationships between them, an application model will contain components, interfaces and component interactions, and an infrastructure model will contain locations, nodes, connections between nodes, and the placement of components onto nodes.
- A view (which may be represented using several diagrams) refers to any modelling elements it needs to in order to communicate the architecture to a particular set of stakeholders that share a common set of concerns. For example, a security view may refer to elements in a data model, application model and infrastructure model. These views then form a significant part of any “packaged” architecture description that is then communicated to different stakeholder groups.
With this basic understanding, I then discuss a diagram like the one shown below and ask a very simple question – “what is the most important element shown on this diagram?”. Almost all discussions dive immediately into the different models, different views, the differences between models and views, the need for a separate architecture description and the like. Given the diagram below, this is “left-to-right” thinking where architects are often focused on the models they create and the views that can be derived from these models.
I then ask another question – “why do we document a software architecture?”. It’s not long before the focus changes to stakeholders for, indeed, stakeholders are the most important element shown on the diagram. And understanding who you really need to communicate with, and how, is the right starting point for documenting a software architecture. How else do you know how the architecture documentation should be packaged, what views to select and, therefore, what models to produce? As far as the diagram is concerned, it’s “right-to-left” thinking. And by that, I mean that the logical sequence in which to derive those elements that will be used to communicate the architecture is:
- Identify the stakeholder groups. As mentioned above, when documenting a software architecture, the first thing to understand is the target audience. Stakeholders can be organized into groups that share a set of related concerns. The two groups of stakeholders shown in the figure are Developers and Testers.
- Select the views. Having identified the stakeholder groups, we then need to identify the corresponding views that will allow their concerns to be expressed. Each view requires information held in certain work products (such as models) so that the architecture can be communicated to the identified stakeholders in an appropriate manner
- Create the work products. The architect (or architecture team) populates the work products accordingly. For example, we may add elements to any models that we have decided to create.
- Package the architecture description. Rather than communicating the architecture using all of the work products that have been created, we typically package elements in a form that is more-easily consumed by the stakeholders (for example, all stakeholders may not have access to any modeling tools used to create certain work products). The diagram above shows the architect creating a Software Architecture Description deliverable. This deliverable is organized by the different views on the architecture.