Lean Architecture Principle #9: Comprehensible over comprehensiveness

21 Jul, 2010

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
an organisation.
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.

Newest Most Voted
Inline Feedbacks
View all comments

[…] This post was mentioned on Twitter by Arnon Rotem-Gal-Oz and Xebia BV, Diego Magalhães. Diego Magalhães said: RT @arnonrgo: Svan Denberg : Lean Architecture Principle #9: Comprehensible over comprehensiveness […]

Gerbrand van Dieijen
Gerbrand van Dieijen
12 years ago

If you’ve created a specification that is so detailed and complete that nothing has to be questioned by software developers you might as well automatically generate software based on that specification.

12 years ago

You hit the nail right on the head. As a matter of fact, the company I worked for at the time was specialized in MDA/MDD techniques. Sadly, due to governmental policies, the project had to be tendered. Still it’s a clear example of how you should keep in mind who the audience of the documentation/specification is. Communication is all about the right message in the right format!

12 years ago

I agree with the other comments.
A specification perfectly precise is just code, although it is might be more graphical than textual in nature … (BTW, I agree that code generation should be really efficient). And the target audience of code is the developpers themselves, not the analysts or managers…
Documentation relevant to analysts should be in a language they understand fully.
I would advise to use the Ubiquitous language for that (yes, I have DDD influence !).
But I got bitten also by the separation between business documentation and the corresponding code, that leads to maintenance problems as we all know. My long term ideal (I know no tool for that) would be :
* hold the business language with the relevant source code files (as comments for example, see the javadoc idea)
* generate an analyst view that only includes what is meaningful to them ; that view should be read-only, so any modification would impact the source
You could get additional benefits (for free?) , such as versioning of the business documentation alongside the corresponding code.
You could also consider adding in the source files also end-user help information (for generating the end-user help), and examples/tests (useful for automatic testing, or generating the testing manual)(test results could also fit in the source itself, next to the example).

12 years ago

There are a few typos in my previous comment …
In the paragraph “But I got…” :
* change “business language” to “business documentation”
* change “be read-only” to “not be read-only”
* add a final dot
In the last paragraph :
* remove the second “also”
* before “for automatic testing”, add “for development, “

Explore related posts