Documented Architecture? Of What Value Exactly?

Thank you for subscribing to Work Thoughts. I am an Enterprise Architect with almost two decades' experience in IT. I share my experience - both hard and soft skills - in fun ways through these articles. Share the fun. :)

Technical teams in my experience often wonder why we have to spend so much time developing catalogs, matrices and diagrams that describe the solutions we are trying to build. You hear questions like, "So, you want to draw right?" alluding to the hidden objection to what is considered a futile activity. You could also hear statements like "This is too long! We are going live next week" "Fail fast, fail forward..." "When we get to that bridge we shall cross it" "Who is going to read all this?" All these objections are not farfetched given the rate at which organizations desire to roll our digital offerings in this day and age.

One simplistic analogy we often bring up in such conversations is the development of real estate. So let me ask two questions we might ask colleagues with this mindset:

1. What process did you follow when building your home? Did you finish the building and then ask the architects to "draw" it? Rolling out without a documented plan is a method of working. It works well in some contexts. For example, several huts in my village were built very quickly with no documented plan. This might not work for your mansion in Orlando, Florida. Context is key.
2. What would constitute an "Agile Home"? One in which we build the structure, living room and one room nd kitchen as the "Minimum Viable Home" (MVH) then move in while we complete the rest? How about a "room and palour self-contained" which you intend to expand later (hoping you bought the right size of land). Plausible. Again, context.

The questions are not intended to trivialize Agile concepts but to point out that some contexts demand that we evaluate carefully how we apply principles as incredibly valuable as they are in the industry. So let's get back to the core question: Why would we need to reference architecture artefacts?

Why Do We Need Artefacts?

Auditing

In my experience, when we write our procedures, we are making promises; these promises rope us in. The auditor's job is to ensure that what we are doing practically aligns with the we have presented in documentation. If we have indicated that all production systems should have architecture artefacts that describe them in detail, those artefacts must be available. We cannot afford to simply skip them because we need to move faster. If we need to change the granularity of documentation, then we must re-write our policies and procedures.

Root Cause Analysis

Most root cause analysis sessions I have been a part of in my career typically involve a long list of questions around how components of the impacted system talk to each other. Questions about what talks to what and how are often repeated like we are discovering the system every single time. In the movies when soldiers need to develop a plan of action, they bring out a map. If the map is reliable, then the strategy is tenable. If we do not take time to develop maps of our enterprise, we will ask the same questions every time we need to get to the bottom of a problem.

Change Impact Analysis

Nimble startups with five services in AWS and one or two customer-facing products can afford to deploy changes and rollback at will. Massive Social Media platforms designed with eventual consistency in mind from the beginning are fully familiar with managing changes in the context of small subsets of the infrastructure. On the other hand, enterprises with legacy systems as part of the enterprise architecture must have a clear understanding of impact. Accurate artefacts help make this possible.

Long Term Planning

Most enterprise these days are charting a course that has "digital transformation" as part of the picture. Well-dressed consultants in body and mind are often invited to develop long presentations that help such organizations to move forward. Incidentally, the first stage of any program of this nature is an assessment of what already exists - the AS-IS enterprise architecture. More often than not, these consultants would question system custodians in the company about the AS-IS, sometimes they even ask for - hold your breath - documented architecture. The accuracy of the future state description has a lot of dependency on the understanding of the baseline. Remember, the case is different for nimble startups that are just beginning.

Let's Be Fair

Some organizations may never need impact analysis because tools which perform discovery have made an understanding of the entire environment alive. Some do not bother with audits because they have not bound themselves to any such requirement with their documentation. However, external bodies such as regulators may influence this in certain industries. As mentioned earlier, some have never had monoliths. They are cloud-native from the start so long term planning for them does not really make sense. They have to be incredibly flexible.

Conclusion

Most best practice frameworks are very well thought through by those who develop them but like all humans, they are biased by their background. Deeper study and practical deployment often reveals the short comings of those frameworks over times. Wise organizations think through the frameworks and to determine how best to adapt them. Artefacts, as boring as they may be to develop turn out to be quite useful in certain scenarios. In some cases, the usefulness is not as much in the final product as in the process of collaboratively developing the artefact.

So let us know, in your experience, are architecture artefacts still useful? How much time do you spend building them?