In the previous installment, we discussed the role that the architectural discipline has in producing quality code in an agile context. In particular, we focused on the cadence of the architectural process —the agile production of Initial, Working, Target and Transfer architectures to iteratively inform development. In this piece, we will focus on broad concepts of quality in architectural documentation. This will serve as context as we transition into discussing the practice of the architecture discipline and introduce the REAPS methodology.
“Architecture, like language, can be used to reveal or conceal truth. In the wrong hands, a convincing story can cause people to believe nonsense is truth. Likewise, in the wrong hands, Architecture can cause business to believe a pile of technical debt is a solid company asset.”
The origin of quality architecture is in how it is used. In general, agile architecture should stress communication between stakeholders over notational sophistication. While UML 2.x 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 2.x. 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.
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 insure 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 to 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. Such 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.
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 2.x (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.
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 shows them what the latent dependencies between pieces are. 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 will do.
· It must be a provable solution: A good architecture should be provable with code. As relevant and necessary, architects and lead developers should produce stub implementations that link particular problems with proposed architectural solutions.
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 criterion around how well architectural documentation fills those ambitions.
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.
About the Author
Davin Lafon currently serves as director of Artificial Intelligence at Phase Change, where he is leading the research and development of a collaborative AI for software development, as well as designing the architectures that will scale it. Prior to that, Davin was a practice director for ProKarma’s Digital Integration practice, which enables large-scale transformation by bringing together data from across the digital sphere.
Davin, whose expertise includes mobility, strategy and enterprise architecture, began his career as an artificial intelligence research engineer at Carnegie Mellon. He went on to found a consulting firm in the mobility space, where he helped Fortune 100 companies and privately held financial sector organizations set mobility strategy and develop their enterprise architecture.
References and Footnotes