What is the Right Level of Detail for My Agile Models?
Jul 7, 2020
In previous blog posts, we discussed the use of architecture models in agile development. Probably the most commonly asked questions in modeling is: “What is the right level of detail for my models?” And in an agile context this is perhaps asked even more often.
However, this is not something you can simply define up-front. There is no single, ‘right’ level of detail. This strongly depends on the context and objectives of your modeling effort.
Of course, it is not a good idea to document everything in excruciating detail. Models need to be precise enough for their intended purpose. For example, to help team members understand a solution going forward; DevOps experts to deploy it and resolve issues (also think of integration testing, for instance); other teams to reuse components and services; and perhaps most importantly, anyone who needs to make changes in the future without having access to the original designers and builders. This is where the intent of the architecture is especially important.
Having models that are too detailed often leads to problems in maintaining them, simply because you cannot spare the effort needed to keep everything up-to-date. That in turn leads to models that age quickly, and sometimes people turning away from modeling altogether because the models they need to work with are always outdated anyway. This is clearly not the way to go.
So you should never model more than you are able to maintain (unless it is a one-shot, throwaway model). But how do you then decide on the level of detail?
There are two complementary approaches to take. First of all, arriving at a good, useful level of detail is an iterative process in itself. You can use the agile process itself to improve this. In a retrospective you can discuss this and thus fine tune your approach. Did you have the right information at the right time? Was the effort needed to create or update your models feasible and worth it? Like any other activity in an agile approach, modeling should be subject to this continuous improvement of your way of working.
Secondly, you can use a risk-based approach to decide where you need more detail. Most agile methods are not very specific on this, but some of their predecessors like the Unified Process are explicitly risk-focused and aim to address the most critical risks early on in the process. In line with this, you should create more detailed models for those areas of an architecture or design where the risks are greatest, and less detail where you can decide on the fly and the consequences of an error are limited. For instance, deciding on an infrastructural technology is often high-risk, because of the cost involved and to avoid the time and effort it will take to reverse that decision when it turns out to be the wrong choice after all. Other common high-risk areas are health & safety, security, and compliance. Think of personally identifiable information (PII) risk, financial transaction handling, manufacturing process control, etc.
This also implies that your models will not have a single, similar level of detail across the board. Moreover, even aiming for such a standardized level of detail may lead you to spend effort where it is not really needed, and conversely, to lack the time for those areas where it really counts. So any modeling approach that tries to tell modelers up-front what the ‘right’ level of detail is, will most likely result in models that are almost always at a ‘wrong’ level of detail – either too granular or too general.
