PK company
POSTED : October 26, 2018
BY : Concentrix Catalyst

Our previous installment looked at the role of architecture in ensuring quality in an Agile context. In this piece, we’ll look a little deeper at architecture and architectural documentation to help define some guideposts for what ‘good’ architecture is in the agile context.

In general, agile architecture should stress communication between stakeholders over notational sophistication. While UML diagrams such as the Class Diagram can be high enough in detail that code can be generated directly from the diagram, such diagrams end up being brittle and as difficult (or even more difficult) to revise as the underlying code itself, thus rendering them of little value in a fast-changing, rapidly iterating environment built around the idea of continuous change. Additionally, agile architecture should be communicative and meaningful to all stakeholders, not just those technically sophisticated enough to understand UML. As a result, architectural documentation should use sophisticated formalisms like UML Class diagrams sparingly, and only where there is a defined need for high-detail documentation for identified sets of developer stakeholders.

On the other hand, architectures become effectively useless documents when they do not provide enough information to be specific in their communication. Take, for example, the classic ‘stack of colored blocks’ architecture.

We’ve all suffered through it before, chances are we’ll suffer through it again. A stack of colored blocks that pretends to communicate something meaningful about a system, but in fact says nothing of any value.

While not inconsistent with much of what passes for architectural documentation in the industry today, this diagram is so vague as to be devoid of value, given that the stated aim of agile architecture is to “serve as a vehicle for interactive communication between scrum team stakeholders, advance communication and understanding with client stakeholders, support and enable change and help ensure quality software delivery”.

In a nutshell, this diagram communicates very little to technical stakeholders such as developers. How to code the system components, how the components communicate, what their dependencies are and what should be modifiable or testable in isolation — all of this is unclear (Can the Communication Layer access the Data layer through the Logging and Data Transport thingie? Really? Is the Bus Asynch? Blocking?). From the Scrum/PM perspective, there is no understanding of how the system components align with features, and what components need to be built first. From the ownership perspective, there is little here that can be used to understand the value the system brings, or what business drivers are satisfied by this arrangement of components.

Agile architecture must strike a balance between these two extremes. ‘Good’ agile architecture should be technically clear enough to articulate development choices in a way that is helpful to developers, yet also be informative to Scrum/PM stakeholders, so that they can understand implementation dependencies between components, and draw a line between components and features.

Attributes of quality architecture

All architectural documentation produced in Agile projects should conform to the standards of ‘good’ architecture. Architectural documentation that is ‘good’ has the following characteristics:

Good Architectural documentation is communicative to its audience: An architecture is meaningful if and only if it conveys actionable information to specific classes of stakeholders. For example, an architecture produced for security auditors should convey information about data types, PII, encryption levels or network topology, while an architectural document provided to project managers should help them understand what the major system components are, how they rely on each other, and where the complexity/risk resides. Typically a body of architectural documentation has many stakeholders in its audience. The art of the science is to speak to all of them meaningfully.

Taken as a body of documentation, a ‘good’ architecture will be informative to many different stakeholders. Engineers will understand how to build it, Project Managers will understand how to plan it, and Ownership will understand how it speaks to their business needs.


Good Architectural documentation relies on explanation over notation: The components, connectors and flow of information in the system documented should be clearly called out in easily readable legends that convey information to the targeted audience. Even in diagrams where UML (or other) notation is strictly followed, legends should explain the key points, unless the intended audience for the document only includes those experienced in the notational system (e.g. UML Class Diagram for developer consumption).

Good Architectural documentation meaningfully constrains the system: When used as a guide for implementation, a good architecture must allow developers to make clear implementation choices based on what is consistent or inconsistent with the architecture. There may be an infinite number of ways to implement a stack of colored blocks architecture, but a ‘good’ architecture should impose meaningful and helpful constraints on the code and its implementation choices.

Even the most simple systems can be built in a nearly infinite number of ways. Two engineers looking at a bad Architecture will see two different builds. But a thousand engineers looking at a good Architecture will all see the same one.

Good Architectural documentation conveys critical information: From a system engineer’s perspective, good documentation clearly explains the computational objects (classes, packages, or whole applications), how they are connected (e.g. network protocol and data packaging format), their context (e.g. ‘server’) and how information flows between them (e.g. sequencing). From a Project Manager perspective, a good architecture should show what the latent build dependencies are between pieces, features and components. From a business perspective, good documentation shows them how the system will respond to their business needs and unique drivers.

Good Architectural documentation chooses simplicity over sophistication: Agile architecture should seek to define the most simple, most achievable structures that solve real-world code issues and support relevant qualities (e.g. modifiability, maintainability, etc). A ‘good’ architecture defines the least complex system to achieve the desired outcome.

  • It chooses established solutions over novel solutions: Agile architecture does not seek to re-invent wheels when existing designs, conventions or solutions will do.
  • It must be a provable solution: A good architecture should be provable with code[1]. As relevant and necessary, architects and lead developers should produce stub implementations that link particular problems with proposed architectural solutions.

Bad Architectural documentation is littered with unicorns and rainbows (and other more malodorous constructs). Good Architecture is practical, solves real problems with minimal fuss, and most importantly can be proven with code.


In our earlier article in this series, we looked at the role architecture plays in the Agile software development process, and how Architecture can serve as a way to solve problems and communicate between various stakeholders. In this piece, we advanced an analysis framework that establishes criteria around how well architectural documentation fills those ambitions.

What’s next?

In the next article, we’ll look at our first example of how to translate this guidance into actual Architectural artifacts. From there we’ll look at defining Roles and Responsibilities around Architecture in the Agile context.


Tags: , , , ,