It’s not a complete architecture unless…

I often get given parts of architecture and am told the architecture is complete. This blog shows the bare minimums I use for assessing completeness.

Here I am laying down some minimums I ask for before I consider architecture to be complete, in terms of the types of things I need to see. In terms of actual subject matter, because the world changes is may be that architecture never stays static.

It can be very frustrating to repeatedly be told an architecture is ready when the basics are missing, so I thought I would lay them down here for all to see.

Although I am speaking from my own perspective, much of what I think, and how I practice architecture aligns to standards such as ISO 42010.

Its worth noting that I will sometimes be a bit relaxed with how I assess architecture depending on who is giving it to me. I don’t want to lay down law so much as provide direction for improvement and avoid having to spend to much time in a cycle of reviews. This blog is written with architects that work for/with me in mind.

It’s not a complete architecture unless it clearly identifies requirements

Requirements should be in some kind of list, saying where the requirement comes from, where it goes to, who is managing it, the priority and why it exists. Often extra information around status is also directly available on a requirements list. It is not enough to say the requirements are in the solution description we sent to the customer.  The solution description is normally a text document, and unless you pull the requirements out of it, its easy to miss some of them. Also the solution descriptions normally are very customer focused. There are a whole bunch of internal requirements solutions normally have to adhere to if we are designing something to be compliant with ISO 27k for example. Have requirements in a list, so we can address them one by one. Take a look at the TOGAF ADM Model – requirements management is at the heart of this model. Understanding needs of stakeholders is key to ISO 42010 as well.

It’s not a complete architecture unless it shows how requirements are met

Every single requirement has to be addressed by a solution or it is a risk or vulnerability; because by definition if you don’t address a requirement, somebodies needs are not being managed. Its OK if an architecture will not address a requirement – but that kind of a decision still needs to be tracked in your design; the polite thing is to agree it with the originator of the requirement or failing that to agree it with someone who has authority to make such decisions.

If you cannot show how requirements are met, the architects coming after you will have a hard time understanding why architecture decisions were made. This can, for example, lead to people innocently making changes at a technical level that breaks how things work from a business one.

ISO 42010 says that architecture concerns should be framed in one or more views.

Collaboration

It’s not a complete architecture unless its been agreed with the stakeholders

Your architecture should be identifying stakeholders – the people it provides value to. It stands to reason that means that how it provides value is of interest to those stakeholders.  If your architecture doesn’t meet the stakeholder needs, it hasn’t succeeded. This doesn’t mean all stakeholders will always be happy. Quite often architecture may be an agreed compromise. A customer is not the only stakeholder!

ISO 42010 has some great examples of different stakeholders your architecture may want to consider.

It’s not a complete architecture unless it addresses the appropriate aspects.

I speak often about covering IT Aspects. Having a brilliant diagram of how different system components fit together is almost never enough.

We have responsabilities to follow regulation, and those fancy technical designs are often going to be operated by someone who didn’t design the solution. This means people need to understand how the technologies work. How we operate things, sell them, and implement them all need to be considered as part of design and communicated.

When this isn’t done as part of an architecture design you end up quite often with something that isn’t scalable. Sometimes what will happen is the talented technical designer will hold the hands of the people that will support things and for a while things will run OK. Over time, people change in the different roles, and what was once laid out clearly becomes less clear as the IT equivalent of Chinese whispers happens.

Of course because you haven’t built and implemented a consistent design people may do things in different ways, leading to cost overhead, a loss in scale-ability, trace-ability and a diminished ability to do any kind of real optimization or effective cost reduction.

It’s not a complete architecture unless its been documented as one contiguous solution

If you do not have all the parts of a solution documented together in one place, or at least tightly connected to each other, its very easy to lose things, and to lose track of your solution.  That doesn’t mean everything is in one word document. If you are using word to describe your solution then its OK to refer to other documents containing information you rely on – such as the requirements. If we do this though,  we have to make sure that a) everyone reading a document actually has access to all the associated links, b) that information across the different information sources is properly versioned.

When you don’t properly maintain versions then you can end up in a situation where a solution refers to a requirements Excel, and someone else developing requirements may make changes that your solution doesn’t address, leading to a great deal of confusion for anyone reading your work. A good architect will be aware of the company documentation standards, and will be also designing solutions that cover whichever modelling standards are in place.

It’s also not OK to make decisions in meetings and not document them, or only documenting them in a set of meeting minutes. Its so very easy in those cases for a decision made in a meeting half a year ago to just disappear.

ISO 42010 makes mention of tracking key decisions in a log. I find that keeping things together relating to a particular work stream makes a lot of sense. It doesn’t have to be in depth – just knowing the date, the person or people working on something – and what they achieved – can save a lot of time when new people are on-boarded or when questions are raised during escalations.

Anyone that’s read my blogs or knows me, knows that I prefer to have my architecture be in a model, rather than documents.

Summing It Up…

If you have a good technical solution – that’s great. I do not argue that a technical diagram detailing how servers connect to different networks is not a valid part of architecture. It is. There’s also an argument that architecture always exists whether it is documented or not. Take a look at my blog on Designing Architecture Through Document Templates if you are interested in that..

The point i really want to make is that in order to have an architecture solution, you need to have clearly identified & scoped the problem, and show exactly how it is that you are keeping promises to your stakeholders, Not doing this will more often or not lead to extra cost later on down the road.