This is the ninth post in a series of blog posts discussing Lean Architecture principles. Each post discusses one principle. Applying these principles results in an architecture (process) that is better connected to the business, better able to deal with change and more cohesive. The ninth principle we
discuss is “Comprehensible over Comprehensiveness”.
Documentation is important in architecture. Architecture is primarily a long-term thing. Even though in a lean-style architecture the focus is on adding value as early as posible, the results of our actions last for the lifetime of the architecture itself. This usually spans years. If we take a step back and reflect on architecture and value creation, we can ask ourself why we write documentation. The prime objective of writing documentation is communication. We want to communicate why we made certain choices, why we standardized on a certain infrastructure. We write things down because someday, we will no longer be there to communicate these things! The goal of (architectural-)documentation is to create some kind of “organisational memory”. Documentation describes the knowledge that should be retained within
The focus of documentation is communication. Communication is about delivering a message to a public. Each public has their own way of approaching. To create documentation that will actually be read, we have to take the audience into account. Documentation needs to be comprehensible for the targeted audience, or it will become TAGRI (They Aren’t Gonna Read It) documentation (thanks to
Scott Ambler). For some audiences it may be important to be as comprehensive as possible, however, just like the agile manifesto, we prefer comprehensible over comprehensiveness.
Documentation should also be just good enough, see our earlier principles of ”Just in time, just enough” and “Travel Light“. Any architectural document should provide just enough content to “get the job done” and nothing more. The hard part is determining what is good enough. Also, artifacts will become less
“good enough” over time. This implies that artifacts are also living things, that should be updated and expanded incrementally.
For example, in my not to recent past, I worked in a software company that wrote specifications for (software)components. These specifications were written in a slightly formalized form of natural language. Naturally this introduced a lack of clarity, leading to questions and new versions of the
specification. In order to prevent this tedious and time-consuming feedback-loop, the descission was made to create new specifications using UML and OCL in a way as formal as possible. This led to very detailed specifications, almost mathematically sound and complete. However, these specifications
were meant to be used in tenders. The audience of the specifications were accountmanagers, businessanalist and other business focused people. These people had little to none experience using and reading formal languages, therefore the specifcation was completely unusable. Had the specification been comprehensible, communication would have been easier.
So how does this match the 3 C’s of architecture? We obviously gain better connection to the business if we communicate in a manner that is comprehensible.This was the ninth post in a series of blog posts on Lean Architecture principles, the next one will follow in about a week.