Clarity: One of the Most Important (and Often Ignored) Aspects of Software Architecture
When designing and building digital solutions there are many principles and best practices that should be applied to ensure your solution is secure, performs well, can scale, is easy and cost effective to run, and ultimately delivers value for the business. This post is about none of those — but rather a quality which is often not given enough time, investment and focus, and one which, when isn’t there, will be the root of many problems.
This quality is Clarity.
What is Clarity
Clarity in this context is an easy to understand systems design, or software architecture, that communicates what the solution does, what it’s made of, why key technology decisions have been made, what responsibilities each part of the system has and how they talk to other parts, and who is responsible for each part.
If an architecture can be easily described and answer the questions above it is considered coherent and cohesive — logical, consistent and a unified whole.
Why Clarity is Important
The primary reason that clarity is important is for communication. Having worked on digital projects over the last 20 odd years, I still maintain once of the biggest causes of project turmoil is poor communication. At best it can cause friction and at worst it can derail multi-million dollar projects.
In the software engineering domain, communication of technical design thinking and rationale can be challenging between technical and non-technical stakeholders, and within pure technical groups themselves. People have different backgrounds, levels of expertise, perspectives, ingrained thought processes, biases, allegiances, opinions and language abilities.
With all of these factors working against achieving a shared understanding, making decisions and moving forward in the same direction can feel like swimming against a strong current with your arms tied behind your back.
And the bigger the project the bigger the impact of a lack of clarity and understanding will be.
How to Create Clarity
With so much at stake what is the best way to create clarity and avoid communication black holes which can swallow up time, money and sanity? Here are a few tips to help guide you on your journey to describing technology design in a clear and coherent way, and creating much needed alignment when engineering digital solutions.
- Use Visual Tools
The saying that a picture is worth a thousand words is as vital as ever. Use diagrams and collaborative drawing tools to describe and discuss your architecture. UML isn’t dead, use it where needed. With Covid, tools like Miro have gained popularity visual collaboration and communication.
2. Use Prototypes and POCs
If picture can save a thousand words, a prototype can save a thousand meetings. Where there is deep confusion and doubt, create a prototype or build a Proof of Concept (POC) to communicate thinking and allow deeper investigation into a design approach.
3. Hire Strong Communicators
In my industry, senior technology roles have emerged which are oriented towards designing technology solutions and being able to articulate those designs to all concerned. Technical Architects, Solution Architects, Tech Leads are some of the labels they go by. Whatever you like to call these folks, make sure that they are good at listening, articulating technical design to both technical and non-technical audiences, and the rationale behind decisions.
4. Standardise Outputs
Employ common architecture modelling approaches such as the 4+1 Model or the C4 Model. Expressing your architecture with boxes and arrows and providing different perspectives is essential to system design communication. Standardising on the outputs will help teams quickly get to grips with familiar ways of expressing technical architecture.
Also, UML isn’t dead. Use it if you feel will help your cause.
5. Use Patterns and Common Terminology
Many problems that engineers come up against have been encountered before. This is why there is a lexicon of patterns and terminology that can be drawn upon to describe technical design approaches to solve technology problems. Defer to common patterns and terminology where possible to bridge translation gaps between people. In software architecture the common resources are the Gang of Four patterns, Enterprise Architecture Patterns derived by the mighty Martin Fowler and cluster of uber nerds, Domain Driven Design which seeks to accommodate the language of the business into technology design, and Behavioural Driven Design which drives collaboration and a ubiquitous language.
6. Avoid Ambiguous Terminology
On the flip side of tip #5, avoid ambiguous terms that are open to interpretation.
7. Stop if There is Misalignment
In the pressures of project delivery, it’s easy to forge ahead regardless if other team members, teams or entities are not aligned. Governance and Steering is the mechanism often put in place to keep things on track. Unfortunately, Governance is often paid lip service to and not the firm hand that it is initially billed to be. Senior folks are always pretty busy. Nevertheless, having a finger on the pulse of a project, spotting confusion and stopping when needed (senior judgement needed) is essential. To throw another adage into the mix, one step back to change direction is better than two steps forward in the wrong direction.
I’ll stop there at lucky number #7. Always interested to hear how others tackle driving clarity from ambiguity, and achieving understanding and alignment when confusion is rife, especially in the software engineering domain. Ideas, thoughts and reference materials are most welcome.
