Document Well, Build Better: The Impact of Software Documentation on Architecture

This article aims to address issues that may arise when documentation is missing and how to avoid them by adopting these two frameworks — C4 model and “4+1” architectural view model.

One of the biggest problems I have faced during my professional life as a software engineer is whenever I embrace a new project I feel the same difficulties in catching the gist of the system architecture. Nonetheless, I have found similarities among all these projects such as documentation artefacts that are hard to understand, diagrams mixing different levels of granularity, inconsistent notations, deprecated documentation, or worse, no documentation at all.

The consequences of inadequate documentation are vast and unpredictable. When a project does not encompass the required assets to communicate its architecture to the development teams, we might be contributing to an increase in their anxiety levels triggering the impostor syndrome, and the architecture initially sketched up will probably end up in something very different, putting at risk the customer expectations.

To better understand this purpose I would like to share the definition of software architecture proposed by the Software Engineering Institute, Carnegie Mellon University:

“The software architecture of a system is the set of structures needed to reason about the system, which comprise software elements, relations among them, and properties of both.” [1]

Thus, the following sections cover some good practices for creating this set of structures so that we can effectively communicate them and keep everyone on the same page.

Traditional Approaches

Almost every project has a diagram full of boxes and lines. It is very usual to see when a new member asks for some documentation the older ones rush to share the holy grail of architecture. For sure, diagrams like the one below (Figure 1) are very well-known to all of us once they used to be peppered all around.

Figure 1 — Boxes and lines diagram

Concurrently, it is also quite common to find diagrams like the one shared below (Figure 2) in presentations of consulting firms, as they bridge the gap between technical complexity and business objectives.

Figure 2 — Architecture of SAP S/4HANA Embedded Analytics [2]

However, this sort of diagram is closer to marketecture (marketing + architecture) rather than a set of assets available to reason about a system. At this level, architectural diagrams are not a sales tool. The software development teams do not need to be persuaded because they will not buy anything. Instead, they are seeking the “truth”. Marketecture might sound easy for its authors, but it is hard for those who will implement it.

Another usual approach, when a new project or iteration is up to start is to reason about software based on a user interface design mockup.

Figure 3 — User interface design mockup

While this upfront approach is useful for the early stages of the project it might be dangerous for the following ones. In these cases, at the very first step, development teams must deconstruct the mockups in order to extract the requirements otherwise the consequences at the architecture level might be significant if the use cases are not correctly identified, and the architecture will be negatively affected.

Therefore, considering the above diagrams, some questions arise:

1. What do these boxes mean? Components? Classes?
2. What do these lines mean? Inheritance? Dependency? Data flow?
3. What does it mean each one of the horizontal layers?
4. Where are these components deployed?
5. What are the runtime variation points?

Beyond them, there are many more which are still unanswered. This means this level of detail is not enough. Thus in theoretical terms what sort of structures do we need to reason about a software system and how should they be organized? The following list provides characteristics that must be comprised by those structures:

• Multiple views of the system: today's systems are too wide and complex to be captured into a single artefact because they have to deal with abstraction, decomposition/composition, style and esthetics [4]. Views show a limited scope of the structures as they really exist in the software and hardware.
• Hierarchical structures: computing systems are organized around abstraction layers, the process of generalizing concrete details allows humans to create large systems by focusing on a small set of concerns at a time. Multiple views of different abstraction levels help in managing complexity and understanding the system from various levels of detail.
• Integration with the development process: it is important to ensure that design decisions and the structures which support them are well-documented throughout the development lifecycle, preferably using a version control system.

In a very early stage of my career, in one of the projects in which I was involved the whole architectural analysis was based in one of these boxes and arrows diagram. To make matters worse, the project followed a waterfall methodology, and we only collected stakeholder feedback at the end. During our discussions, they made it quite clear that data integrity was the most important quality attribute for this new software piece. The development process went around this diagram however it was ignoring the mapping of the software onto the hardware. Thus, while we were developing, we did not care about redundancy, but when the implementation team deployed the code into production the data integrity was heavily affected by concurrency issues. This happened because the experienced implementation team when deploying the code into production scaled the software and the hardware for redundancy however the software was not prepared once the development environment was a single host. Looking back, I am sure if another view of the software (a deployment diagram) had been provided this incident have been avoided.

In other domains outside software engineering, the current approach is widely used, and we would consider it odd if it were somehow different. Could you imagine a doctor not using a scoped view to study different parts of the human body? Or a civil engineer who does not properly document the electrical or plumbing blueprints?

Figure 4 — Human body views [3]

Probably not. So why have to be any different in software engineering? In the next sections, some suggestions of documentation frameworks are provided to answer this question.

4+1 Architectural View Model

The 4+1 Architectural View model offers a holistic perspective on system architecture by proposing five views:

• Logical View: these views are more focused on the static structure of the software system. They are useful to create a ubiquitous language among all the stakeholders and catch the gist of the system’s functionalities by decomposing them into a set of key abstractions. Supported diagrams: Class Diagram, Object Diagram, Component Diagram, Package Diagram, Composite Structure Diagram [5].
• Process View: this set of views is useful to provide insights about the behavioural aspect of the software system. They describe the sequence of activities between the different components to accomplish the system use cases. Supported diagrams: Activity Diagram, State Machine Diagram, Sequence Diagram, Timing Diagram, Interaction Overview Diagram [5].
• Physical View: shows how software components are mapped onto hardware. They are useful for knowing where components are deployed and for reasoning about availability, scalability, resource allocation, etc. Supported diagrams: Deployment Diagram [5].
• Development View: the decomposition of the system’s functionalities represented in logical views is now packaged into small subsystem modules [4]. These modules are organized into hierarchical layers, by their responsibilities, and with well-defined interfaces, making it easier for development teams to understand how they are distributed across the codebase. Supported diagrams: Component Diagram, Package Diagram [5].

In «Architectural Blueprints — The “4+1” View Model of Software Architecture», Kruchten considers that architecture can be described by these four views and then illustrated by a fifth depicting some use case scenarios [4].

Figure 5 — The “4+1” view model

The “4+1” view model is generic, so other notations and tools can be used, however, UML is usually the preferred notation. Thus, documentation can be developed using multiple tools such as PlantUML, which supports teams in maintaining it throughout the development process.

C4 Model

The C4 offers a framework based on a hierarchical set of diagrams and abstraction layers. The provided notation is a map of the code which allows us to zoom in and out on different abstraction levels [6].

From my experience, the C4 creates a ubiquitous language to be shared among the stakeholders and it represents a powerful way to communicate software architectures, at different levels of detail by telling different stories to different target audiences.

Let’s delve into each abstraction level:

• Software System: this is the highest abstraction level and the most difficult to outline because the term “software system” varies from organization to organization and can assume different concepts like “product”, “domain”, and so forth, but the best way to think it is in light of Conway’s Law [7], therefore you should see it as an enterprise architecture artefact such as a vertical or third-party provider that might encompass common teams or responsibilities.
• Container: represents a single deployable unit like an application or database.
• Component: this is a hugely overloaded term in the software development industry, but in this case, a component does not represent a runtime unit by itself but rather a static part of the system which holds a collection of implementation classes behind an interface [4].

Figure 6 — C4 model abstraction levels [6]

These abstraction levels can be mapped into the following diagrams:

1. System Context Diagram
2. Container Diagram
3. Component Diagram
4. Code Diagram (optional)

Figure 7 — C4 different diagram levels [6]

Note that through the provided notation it is possible to create or combine different diagrams for each abstraction layer:

• System Landscape Diagram: provides a static view of how the system is structured.
• Dynamic Diagram: provides a view of how modules interact with each other at runtime to implement a use case.
• Deployment Diagram: provides a view of how the software exists at the infrastructure level.

Besides the modern layout, the C4 is leveraged by multiple tools that support teams to integrate documentation with their development process and help maintain long-lived documentation.

Comparing 4+1 and C4

The two frameworks are very similar, they comprise multiple system views, hierarchical structures, and integration with the development process, hence both can answer the raised questions in the first section.

The 4+1 model might be more suitable for large projects because is not limited by a strict set of diagrams. Whereas the strict structure of the C4 makes it more intelligible, the 4+1 might be more complex when the artefacts are not organized into a document structure like the one outlined below [4].

# Title Page

## Change History

## Table of Contents

- List of Figures

1. Scope
2. References
3. Software Architecture
4. Architectural Goals & Constraints
5. Logical Architecture
6. Process Architecture
7. Development Architecture
8. Physical Architecture
9. Scenarios
10. Size and Performance
11. Quality

## Appendices

- A. Acronyms and Abbreviations
- B. Definitions
- C. Design Principles

For instance, when following a Domain Driven Design (DDD) approach, C4 does not provide the required assets to create a ubiquitous language among all the stakeholders. The proposed diagrams are too technical. In the same way, when discussing the variation points of a feature, C4 does not provide the necessary artefacts to properly document it like the sequence diagrams encompassed by the 4+1 logical view.

In contrast, C4 provides wide tooling to support long-lived documentation like Structurizr, and the notation might be simpler for those who have not mastered UML. Even though C4 does not cover all the views, the simple notation can speed up and leverage communication.

Conclusion

In conclusion, both frameworks are powerful tools to sketch a set of architectural assets that enable all the stakeholders to discuss them, so that the development teams can then take this recipe to implement it. This will ensure more confidence between what the architect thought and what was actually implemented.

Speaking from my own experience, I have been using C4 enhanced by some sequence diagrams when required, and the useless artefacts are omitted. The results and feedback have been satisfactory among all parties, which gives strength to the theory that “the software architecture of a system is the set of structures needed to reason about the system”.

References

[1] L. Bass, P. Clements, R. Kazman, and M. Klein, “Software Architecture in Practice (SEI Series in Software Engineering)”, Addison-Wesley, 2012.

[2] “Manage Your SAP S/4HANA Cloud”, SAP Help Portal. [Online]. Available: https://help.sap.com/docs/SAP_S4HANA_CLOUD/a630d57fc5004c6383e7a81efee7a8bb/599db5e2921c46ac95475567b9aa68c2.html. [Accessed: 24-Mar-2024].

[3] T. Editors of Encyclopaedia Britannica, “Human Body”, Encyclopedia Britannica, Mar. 21, 2024. [Online]. Available: https://www.britannica.com/science/human-body.

[4] P. Kruchten, “Architectural Blueprints — The ‘4+1’ View Model of Software Architecture”, Rational Software Corp.

[5] “4 + 1 views in Modeling System Architecture with UML”, Visual Paradigm Guides, 2023. [Online]. Available: https://guides.visual-paradigm.com/4-1-views-in-modeling-system-architecture-with-uml/. [Accessed: 24-Mar-2024].

[6] C4 Model, “C4 Model”, c4model.com. [Online]. Available: https://c4model.com/. [Accessed: Mar. 20, 2024].

[7] M. E. Conway, “How Do Committees Invent?”, Datamation Magazine, pp. 28–31, Apr. 1968.