Designing good architecture is only half the battle. You also need to be able to communicate your architecture to anybody who is likely to use it, including engineers, testers, product owners, analysts, and managers.

Taking the time to clearly document an architecture is worthwhile as it can make development go much more smoothly. It unites everybody around a common understanding of how a system will work. It defines a shared language that allows everybody to reason about the system. It makes it easier to educate newcomers to the system so they can grasp how it works.

Given how important documentation can be, it is a shame that often forgotten about or produced grudgingly in response to corporate process. Documentation should be baked into any architectural design. But what should this look like, how do we make it useful and how do we prevent it becoming an onerous chore?

Target the audience, not a methodology

One of the more important guidelines for architectural documentation is that you should always write from the reader’s point of view. If the primary intent of documentation is to communicate then any documentation should be written for the target audience.

There are endless ways of representing architecture, from informal boxes and arrows, though to semi-formal methods such as UML and more systematic modelling languages such as Archimate. These approaches all involve trade-offs around clarity, accessibility, and speed of creation.

It can be challenging to get the format right, especially if you are targeting less technical audiences. Weighty methodologies do not always help in this regard as they need too much prior knowledge to interpret. Techniques such UML or Domain Driven Design (DDD) may help to provide a common language for describing a system, but only for a select few. The majority will have trouble understanding UML sequence diagrams or navigating DDD’s invented language of aggregates, values, and entities.

Be aware of different views

You are unlikely to find a “one size fits all” approach to documentation. Different audiences will require different views of the architecture. The construction blueprint expected by development teams will not be the same as the more abstracted view that can be used by managers in planning development.

This is no bad thing. Providing different views that speak to the same architecture can be a test of the strength of your design. Some methodologies bake in the idea of providing different views of architecture, though this can easily get a little over the top. You should be frugal with views and only produce those that are genuinely required by a strong group of stakeholders.

Define a common language

Every system contains its own abstractions, patterns, and specialised terms. These make up the common language that you can use to reason about the system with stakeholders. This should be explicitly defined somewhere otherwise stakeholders will start to build their own, largely conflicting definitions.

A lack of architectural documentation can also make a system completely impenetrable to newcomers. Over time development can become wholly dependent on specific individuals. Entire teams can work on systems without really being clear about how it really works.

Value brevity

One of the most important architectural disciplines is being able to express complex designs in a simple, accessible format. Long complex documents can be intimidating and tend to include irrelevant material that clouds understanding.

You should aim for “just enough” documentation. The bottom line is that if you cannot express a system in a clear and concise format then you are either over-elaborating the solution or may not understand it fully. You should be ruthless in pruning inconsequential detail and focusing on the very most important concepts.

Architectural documentation should explain the main concepts and patterns underpinning the design rather than building a catalogue of implementation detail. Not only will this be more accessible, but it will be easier to maintain and therefore more enduring. Implementations change, while the main architectural concepts tend to be a little more stable.

Explain rather than catalogue

There should be a clear distinction between the architectural documentation that describes the design and the engineering documentation that describes the implementation.

Architectural documentation should explain the main concepts and patterns underpinning the design rather than building a catalogue of implementation detail. Not only will this be more accessible, but it will be easier to maintain and therefore more enduring. Implementations change, while the main architectural concepts tend to be a little more stable.

The best source of implementation documentation is often the code itself. It will certainly be the most up to date, but not always the easiest to read. Any supporting implementation documentation is best kept in source control alongside the code base. This will help to give engineers a much-needed sense of ownership over their documentation. It will also make it more likely to remain up to date by integrating it with regular code production workflows.

Diagrams are overrated

In many cases, the act of documenting a design benefits the architect more than any other stakeholder. Creating a diagram is an opportunity to organise your own thoughts, get your head around the solution and learn how to express it clearly. Just be aware that not everybody will be able to make sense of a complex diagram.

In the absence of a clear methodology, many architectural diagrams resort to the dreaded “boxes and arrows” style that can resemble nightmarish wiring diagrams. These often fail to convey sufficient context to be meaningful. You should aim at the very least to keep the level of abstraction consistent, control complexity, define clear scope and make sure that everything is coherently labelled.

Diagrams should be self-describing, specific and consistent. They do not have to follow a strict methodology, but an awareness of some formal approaches can help. For example, Simon Brown’s C4 model can provide useful guidance around scope, abstraction, and style. Above all they should convey understanding that cannot be expressed more easily in words.

Build a centralised repository

Architectural documentation should be widely available and discoverable. This implies having a central place to keep it. This does not have to be a particularly sophisticated, but it does have to be visible. A simple wiki will do, preferably one that supports search, versioning and commenting.

You will also need to appoint a curator. Somebody will need to take responsibility for organising structure, pruning abandoned drafts, and managing expired or dated content. This just does not happen through informal collaboration.

Encourage on-going peer review

Architectural documentation also enables peer review. You should be free and open in your method and be willing to share ideas as they emerge. Peer review should be a collaborative process rather than a formal gate where a board of elders review a design carved in stone.

It can be tempting to keep your ideas close to your chest until you feel they have matured. This can help to ferment a formal, closed, and censorious culture. Being genuinely collaborative requires a bit of bravery. You should publish drafts and seek feedback. It can help to bring people with you, warm them up to new concepts but also make it easier to change course if needs be.

Filed under Architecture, Design patterns, Development process and Domain Driven Design.