Value-driven Architecture Documentation

“[We value] working software over comprehensive documentation” features proudly on the front page of the Agile Manifesto. Further down on the page, the authors explain that they do not mean that there is no value in documentation (just less value than in the working software). The practice of documenting architectures in particular has significant positive correlations to solution success factors like predictability, customer satisfaction and technical fit. So we should not abandon the practice of architecture documentation, but we should document our architectures in a way that yields optimum business value.

Bloated architecture documentation

In the past few years, I have helped many organizations modernize their architecture way of working. At the start of these endeavors, the average architecture documents are usually quite large – 200 pages is not abnormal. The templates alone often contain dozens of pages. It didn’t use to be like that – when they started out documenting architectures 15 years or so ago, the templates were nice and small, and focused on a limited number of views, designed to show how a key set of stakeholder concerns had been addressed (such as Philippe Kruchten’s 4+1 Views). However, over the years new insights led to new sections to be added to the template. Concerns that led to business risks or disruptions required new views, such as a Security view or an Integration view. The emerging realization that architecture is a set of design decisions led to the addition of new ‘Architectural decisions’ sections. Outsourcing part of the development sometimes required yet again more detailed views.

The Architecture Document had become the single repository for all architectural knowledge related to a product. This is not a problem per se, except that these same documents were used to show stakeholders that their concerns were addressed by the architecture. Specifically, they were the vehicle for obtaining approval from business owners. Business stakeholders were expected to read, understand and approve hundreds of pages of architecture documentation. Naturally, this led to delays: the architects would spend more and more time preparing the document, and the approvers would take more and more time approving them. Leaving blank parts ‘to be completed later’ did not help, because it increased uncertainty in the stakeholders about the completeness of what they were approving. Documentation bloat had caused the architectural feedback loop to become longer and longer, and caused significant delays when starting up new initiatives.

The value of architecture documentation

It is not surprising that documentation bloat causes organizations to start questioning the added value of architecture documentation: perhaps that value is lower than the cost of the delays the document causes. So let’s see if we can answer this question: “Why were we doing this again?”

In the organizations I work with, I see three main purposes for architecture documentation. We are communicating the architecture to show stakeholders how their concerns are addressed, often in stakeholder-specific views, but also to involve them in the architectural decision process (driving the architectural feedback loop). Additionally, we are communicating the architecture “to the future” for various purposes – let’s call this architectural knowledge preservation. This leads to three distinct business goals for architecture documentation:

  • Explain how stakeholder concerns are addressed (including business, DEV and OPS)
  • Preserve architectural knowledge (for analysis, realization, trouble-shooting,…)
  • Collaborate on architectural decision making

Each of these business goals has manifest business value, e.g. in terms of decision support, driving progress, design quality, risk and cost control.

Separate according to purpose

When we look at the audiences and timing of the three business goals identified above, we quickly see that they require very different language and rhythms in order to provide optimum value:

The insight that the language and timing requirements of these purposes are so different helps us understand that the ideal of “one document as the single repository of architectural knowledge” is not viable. If we want our business stakeholders to quickly grasp that their budget and delivery concerns are addressed, we should not send them a 200 page document and then ask their approval. If we want the development teams to easily learn how to implement our architecture, we should not bother them with exhaustive lists of business rationale behind all the underlying decisions (we should not hide that rationale from them either: sometimes it is needed to make the right development choices).  

The picture above is an example of how to separate the various rhythms and languages of architecture documentation.


The insights above have helped us to significantly reduce the size of the architecture documents presented to stakeholders. In one organization this helped reduce the start-up time of smaller projects from (typically) two months to two weeks – a real boost to agility and benefit to the organization.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.