Standardising Solution Diagrams

As architects, can we at least standardise our solution diagrams?

It still surprises me that even in some corporates, there are solution design diagrams being produced that aren’t based on any standard, or are roughly aligned with some modelling notation at best.

When I first started as a Solution Architect in a small Architecture team for a corporate many years ago, there were no Solution Design templates or standards. When documenting a solution I was left to my own devices to come up with the content and diagrams. Even as a junior architect, I understood the importance of communicating your solution. I always wanted to get the solution on one page and abstract some of the detail to ensure the key stakeholders got the key points. I’d typically end up with a Visio diagram that combined application and infrastructure views, but also at different levels of detail dependent on the specifics of the solution I wanted to highlight.

As the programme of work grew year on year, so did the Architecture team, and the need for some level of standardisation and reuse became clear. The core deliverable of the team was a Solution Design document, so the structure and content of that deliverable was debated and standardised. The reality was that that only got us so far. It didn’t bring any standardisation to diagrams we were creating, no diagrams were reused, every Architect had their favour of viewpoint (which typically reflected their domain strengths). Some organisations resorted to implemented expensive architecture modelling tools, but even a good tool won’t ensure consistency and reuse. Like many standards, good outcomes can still be achieved without them, but consistent outcomes across many individuals is much harder to achieve.

There are a number of professions (I won’t name them for risking starting a separate debate) that argue what they practice is more of an art than a science and hence standards shouldn’t apply. The justification from architects is often that every project and application is different so there is little point in standardising. Then they can’t understand the previous architects work, so they don’t reusable diagrams.

While the likes of UML gave us components diagram that went some way to giving as a standard way to diagram application components and interfaces, there still big gaps. There was still a lack of a modelling language that was sufficiently flexible to replace those “custom” diagrams you created, but sufficient to ensure all areas were considered and standardised sufficiently so that your IT peers can understand them consistently.

“ArchiMate offers a common language for describing the construction and operation of business processes, organizational structures, information flows, IT systems, and technical infrastructure. This is just like an architectural drawing in classical building where the architecture describes the various aspects of the construction and use of a building” (Wikipedia). Most importantly, it’s very flexible and supports many “viewpoints” depending on what you need to communicate, but there rules (which are sometimes broken) just like any real spoken language.

Example archimate diagram illustrating different layers

Example Archimate diagram depicting different layers. CC BY SA 3.0

IT Architecture as a profession is still immature. Imagine if building architects created diagrams with inconsistent detail, or non standard notation. There would surely be more issues in the constructions phases. I found this interesting building architect quote “We were not creating the construction documents for our own use, but providing people who have no prior knowledge of the project, with all of the information that would be needed to construct the project. No matter how great the design of the project may be, if we can’t graphically instruct the contractor on how to construct it, then we have failed in our responsibility to the client.”

I found as an Architecture team manager it was difficult to identify suitable training for the team to support their profession development. There was the obligatory TOGAF training, but unless you were an organisation practicing TOGAF, or had a project big enough to be using the TOGAF framework at some level, that training was hard to put in practice. Solution model diagramming was something the architects do often, but they could be a lot better at it.

At the risk of contradicting myself, there is still a place for those custom hybrid solution diagrams, especially for your business or senior executives audiences where your ability to communicate is king. Just don’t use that as an excuse to not produce additional standards based diagrams for your other IT stakeholders.

David Molesworth, Principal Architect at Cyma Limited

Email: david.molesworth@cyma.co.nz  Twitter: @cymaltd

Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License.