Arc42: Pragmatic software architecture

Architecture has always been important, as it defines the structure of a system and thus forms the basis for maintenance, further development and much more. Arc42 is a proven and pragmatic template for the development, documentation and communication of software architectures and is briefly presented below.

There are many options for architectural documentation, from a simple Single page up to a formal Architectural model.

Each system has exactly one Architecture. Planning and documenting this sensibly has many advantages, because an ad hoc architecture can quickly lead to the development of a suboptimal system and obstruct paths for meaningful further development.

Arc42

Arc42 is a framework for the documentation of software architecture. It is called a framework because it is initially tool-independent. Probably the easiest way to use Arc42 is via a corresponding Word template. In the Download area but there are also many other formats, such as markup for Wiki, Latex or Confluence.

This is possible because the contents are tool-neutral in a gitHub repository is managed. This also means that the content can also be transferred to other formats.

Arc42 is openly licensedThe software is licensed under the Creative Commons License (CC-BY-SA), which also makes commercial use unproblematic. The brains behind Arc42, Gernot Starke and Peter Hruschka, utilize Arc42 through training and consulting. Of course, there are many other contributors.

Structure

Arc42 consists of twelve parts that document all the key aspects of an architecture. The content of the first three chapters sets the context and captures the reader. This is also where the link from technical problems to business-oriented goals is created

There is only ever one architecture, but many architectures are often considered. These are recorded in Part 8, while Part 4 documents the selected solution strategy. The actual architecture documentation is contained in parts 5-7, which show the three most important views of the architecture. Even if diagrams are shown in the picture above, it is not necessary to model them - more on this below.

The last four chapters contain supporting information, whereby the quality scenarios in particular are of great importance.

Implementation with Arc42

Even if there is a Word template, this is not necessarily the most useful form. Although Word is quite universal, it is not really designed for working in a team.

It makes sense to model the architecture, for example with Enterprise Architect - after all, the name says it all, doesn't it?

In the FAQ, caution is advised when using modeling tools and it is recommended to combine their use with a wiki. This will certainly ensure acceptance among readers who have an intuitive web environment. The architects themselves have to deal with several tools and update the diagrams with copy&paste. Nevertheless, they have the opportunity to use all the advantages of model-based work themselves. That seems quite pragmatic to me.

I find the Recommendation to dispense with traceability. I can understand the motivation: After all, maintaining a traceability is indeed time-consuming. On the other hand, well-maintained traceability can also deliver enormous added value. So my advice would be: If (1) a clean traceability model can be stored, (2) a user-friendly working environment is available and (3) there are clearly defined use cases that benefit from traceability, then it makes perfect sense. For example, an implementation with Jama Connect deliver this added value.

Conclusion

For those who need clean architecture documentation but do not yet have the necessary maturity in their organization, Arc42 is certainly a candidate to take a closer look at. Even if it turns out afterwards that the framework is not ideally suited, it still reflects many best practices that can be used without the framework. Apart from the fact that Arc42 can also be easily adapted to your own needs.

Cover picture by Colin Carter on Unsplash