Organize Views around Stakeholders’ Concerns

Different people want to know different things about the software system you are building. Developers on your team will want to know about code organization, deployment, and component interaction. Testers on your team will want to know about the interfaces and communication protocols. The product owner on your team wants to know about technical dependencies and get a sense of the overall progress. New teammates might be overwhelmed by the existing documentation and could benefit with some help getting started. At a minimum, architecture descriptions should describe design decisions, design rationale, and structures in the design.

How we organize this information is important too. The Human rule of design applies equally to how we share details about the design just as much as it applies to the design itself.

When we organize views of the architecture and the various design documentation that goes with it with our stakeholders in mind, then it’s far easier for others to understand the architecture. Doing this requires that we think about what stakeholders want to know. We can then create a view of the architecture unique to that set of related stakeholder concerns. Designing usable documents is how we get people to love our architecture descriptions.

Establish the Viewpoints

A viewpoint defines an approach for describing the architecture from the perspective of a related set of stakeholder concerns. Viewpoints define not only what views you should show but also who the views are for, as well as the notations, vocabulary, and rules to use when creating it. They are a part of the ISO/IEC/IEEE 42010:2011 standard defined in ISO/IEC/IEEE 42010:2011 Systems and software engineering -- Architecture description [Int11].

Viewpoints were designed for use with traditional architecture descriptions, but the general principles apply to any architecture description approach we’ve discussed. Let’s look at an example.

We’ve identified several components in Project Lionheart. Eventually, we’ll need to deploy these components somewhere. The development team needs to know where to deploy them, and the city IT department will need to be told what systems to monitor. It sounds like we need a deployment viewpoint. Here’s one possible view from that viewpoint:

Additional views for the deployment viewpoint will flesh out dependencies among components, platform or third-party software requirements (for example, a particular Linux version), areas of risk, costs, or network topology. The viewpoint itself can consist of both graphical and textual views.

In practice, the information in this example view can be captured in a few ADRs or summarized in an architecture haiku. For the Project Lionheart team, it might be enough to capture the tribal knowledge in the deployment scripts themselves. Add some comments to the scripts to capture design rationale. While this is OK for the development team, a summary table like the one shown will help with the project hand-off to City IT. Always consider the audience when deciding how to document the architecture.

Create Custom Viewpoints

There are several established viewpoint sets you may use to guide your architecture description practices.^[23] I can personally recommend the Software Engineering Institute’s views and beyond approach [BBCG10] as well as Phillipe Krutchen’s 4+1 view model [Kru95], Rozanksi’s and Woods’s viewpoints and perspectives [RW11] approach and Simon Brown’s C4 model [Bro16].

We often organize viewpoints around quality attributes. Viewpoints can also be constructed to satisfy specific stakeholder needs. Here are a few examples:

• A scalability, security, or maintainability viewpoint will demonstrate how the architecture satisfies specific quality attribute scenarios.

• A regulatory viewpoint might provide a particular stakeholder group concerned with regulatory requirements information needed to perform an audit.

• A teachability viewpoint or welcome to the team viewpoint might walk a new teammate through your architecture and development practices with the goal of getting them to commit code on day one.

• A business impact viewpoint might show how different parts of the architecture contribute business value.

Viewpoints are a must in traditional architecture descriptions. With tribal and communal approaches, create viewpoints opportunistically and keep them lightweight. For example, once there are several ADRs in your code repository, create a viewpoint page that connects decision records together to provide overarching context. Mountains of documentation are not required to organize architecture descriptions for human consumption. Be kind to your readers and they will be delighted.

Views help us organize ideas so we can share the architecture effectively. There’s more to an architecture description than just views and design decisions. Why you made the decisions in the first place is just as important.