„"View"-based software architecture documentation

Document effectively using different views

Author: Matthias Künzi, visuellklar

Contribution – Embedded Software Engineering Congress 2018

Documenting a software architecture effectively means recording the relevant information of a software system in a way that allows it to be retrieved when needed. But what exactly constitutes this relevant information, and how can it be recorded in a way that balances effort and benefit? This article addresses precisely this topic.

Starting with the Golden Circle, I will examine the topic of software architecture documentation in three steps. I will begin with the "why." Why should architecture be documented at all? Next, I will address the "how," focusing on view-based documentation. Finally, I will discuss the "what" and demonstrate precisely what should be documented. I hope this will provide a comprehensive overview of the topic.

(See PDF, Image 1: „The golden circle“)

Why?

Documenting software architecture – why? What are the benefits of such documentation?

From my perspective and experience, there are the following two main use cases where architectural documentation is an essential tool:

(See PDF, Figure 2: Main use cases for creating software architecture documentation)

1. Analysis, review, or testing of the software
e.g. for the following tasks:

• Architecture review before the system is built (Earliest Artefact to Analysis)
• ATAM analysis to ensure compliance with imposed quality requirements
• Demonstrate compliance with regulatory requirements (Medtech, Safety…)
• Impact analysis of a software change (additional or modified requirements); maintenance of a software system
• …

2. Explain, schools of the software's structure
e.g. for the following scenarios:

• Explaining the planned system architecture to the development team; ensuring that the software system is built as planned.
• Onboarding new project staff
• Deriving the effort required to develop the system (Work Estimation)
• Deriving suitable interfaces for processing (Work Assignment)
• Demonstrate the design decisions made; prevent the same questions from being raised again later.

There is therefore a clear benefit to architecture documentation. In summary, architecture documentation is an important communication tool in the lifecycle of a software system.

But what about the cost-benefit ratio? How much effort is worth investing in documentation? That's a very good and valid question. Although the use cases listed above are easy to imagine, they are far from being relevant for every system. It's therefore always worthwhile to compare the specific benefits with the effort involved.

That means applying this formula (see. PDF).

If this formula yields a negative value, then the effort required to create documentation is worthwhile. However, one must consider the entire lifecycle of a system. Meaningful architectural documentation will be needed repeatedly throughout its lifecycle.

In particular, proper software architecture documentation is very helpful after initial development. And this is even more true when you consider the relationship between initial development and the maintenance and further development effort of a typical software system.

(See PDF, Figure 3: Total costs / expenses broken down into initial development and maintenance and further development)

„Working software over comprehensive documentation“

This agile principle from the manifesto is correct and important. However, it doesn't say that there shouldn't be any documentation. The opinion here is that it's precisely about finding the right balance between effort and benefit.

It doesn't mean that no documentation should be created, but only that the running software should take precedence over the documentation – or indeed, that meaningful documentation should be a basis for running software.

(See PDF, Figure 4: Working software over comprehensive documentation)

How?

How should meaningful documentation be created? For software architecture documentation, as well as for other types of documentation, there are a few sensible principles:

1. Write for the reader.
2. Avoid unnecessary repetitions.
3. Avoid ambiguities and uncertainties.
4. Use a standard documentation structure wherever possible.
5. Document the background and reasons as well.
6. Make sure the documentation is up-to-date – but avoid unnecessary and frequent updates.
7. Have the documentation checked.

I would like to discuss points 1, 3, and 4 in more detail below:

1. Write for the reader

This also means you should know the stakeholders of your documentation, i.e., the users. It's therefore worthwhile to create a stakeholder map and consider what information each stakeholder should have.

Since different stakeholders have different information needs, it makes sense to create different perspectives and thereby produce comprehensive stakeholder-based documentation.

The following example from anatomy is intended to illustrate the concepts of View, Stakeholder, and Concerns:

(See PDF, Image 5: View, Stakeholders and Concerns)

The following is an excerpt from a specific example of an architecture view:

(See PDF, Figure 6: Excerpt from an architectural view – View Definition)

(See PDF, Image 7: Excerpt from an architectural view)

3. Avoid ambiguities and unclear statements

Clarity is essential for good documentation. Especially for software architecture documentation, a great deal of clarity can be achieved with images, i.e., diagrams. However, caution is advised. Diagrams must be easily understandable. It helps to either use standard diagrams like UML or to explain the symbols and diagram elements with clear legends. The following example of a diagram from an architecture view shows what this could look like:

(See PDF, Figure 8: Architectural diagram with a clear legend)

 4. Use a standard documentation structure if possible.

A clear, consistently used documentation structure is extremely helpful. The following structures for a view as well as for complete software architecture documentation have proven effective (source: SEI):

(See illustration in the PDF)

It should be noted that a view is not simply a diagram, but rather a complete view should be documented using the template above.

What?

What exactly should be documented? Clearly, the "software architecture." But what exactly is that? To understand this, it's worth looking at the definitions of architecture, especially the difference between design and architecture. This, along with the necessary stakeholder information, provides valuable guidance on what should and shouldn't be documented.

„"The set of structures needed to reason about the system, which comprises software elements, relationships among them, and properties of both. The definition emphasizes the plurality of structures present in every software system. These structures, carefully chosen and designed by the architect, are the key to achieving and reasoning about the system's design goals. And those structures are the key to understanding the architecture."“

(From „Documenting Software Architectures“ Views and Beyond (2nd Edition), Clements et al, Addison-Wesley, 2010)

 „"All architecture is design but not all design is architecture. Architecture represents the significant design decisions that shape a system, where significance is measured by cost of change." (Grady Booch)

 In my experience, these definitions are precisely what's needed to ensure that the necessary (essential) documentation is present, but that not every single detail is documented. Furthermore, these definitions also ensure that this type of documentation has a long lifespan and doesn't require constant updates. This is exactly the goal that should be achieved.

Summary

1. The effort and benefits of architectural documentation should be in reasonable proportion.
2. Use views to create a stakeholder-based architecture.
3. Note: A view is not simply a diagram, but contains precisely the information that is relevant to the respective stakeholders.
4. Ensure that all documentation, especially architectural diagrams, is clear and unambiguous. Use a diagram legend if necessary.
5. Document the architecture-relevant parts, not the design and implementation details.

Bibliography and list of sources

• Documenting Software Architectures: Views and Beyond (2nd Edition) by Paul Clements, Felix Bachmann, Len Bass, David Garlan and others. Publisher: Addison-Wesley Professional; 2 edition (October 15, 2010)
• 4+1 architectural view model (Philipp Kruchten)
  https://en.wikipedia.org/wiki/4%2B1_architectural_view_model
• ISO/IEC 42010 https://en.wikipedia.org/wiki/ISO/IEC_42010
  

author

Matthias Künzi (Dipl. El. Ing. HTL, Dipl. Software Ing. FH) has been working at Belimo AG since 2015. In his current role as Head of Software, he brings over 20 years of experience in the implementation of critical software systems in embedded environments. With his own company, "visuellklar," Matthias Künzi advises and supports companies in addressing complex challenges in project and software development, primarily employing visual and agile methodologies.