Designing Architecture through Document Templates

Document templates have some fantastic benefits – but I tend to avoid relying on them heavily when documenting architecture. This blog discusses why.

A question I often get asked – Can you show me a good High Level Design (HLD), or where can I find a good template for a high level design? The reason is normally that those resources want a starting point for doing their own architecture work; and in some cases its because those architects do not have so much experience and want a helping hand. 

Although I speak of Word or Excel, these are just the tools I use at work – we could easily be talking about Open Office applications for example, and facing the same challenges.

Using Word & Excel Documents In Architecture.

There are some definite issues in using Word and Excel for the creation of architecture – and I will run through some of these here, and ways to address them; Although I tend to use models to document rather than documents.

Change Control & Collaboration

Architecture changes by its very nature – as do the inputs to it – such as requirements. Maintaining such a inputs in Word documents is simply not practical when the stored in these formats. The biggest danger here is when you send files via email, multiple versions of the same thing suddenly appear. It is far better to store and version things on a collaborative platform such as Microsoft Teams or SharePoint.

Multiple Contributors

It’s true we have version tracking, and the ability to comment in tools such as Word. When building architectures we do not only manage change at the document level. Individual requirements, for example, need to be under change control. Its better to create requirements on a collaborative platform such as Jira, so we can see when they are created or changed, by who, and we can also lock down releases of requirements so we can be sure everyone is working efficiently together. You could of course refer to Jira and specific releases within your Word Document, and manually control release management, or control it by using some features in SharePoint for example.

Information is hard to manipulate and process

If I have 5 solutions and as an architect I want to understand the common requirements for those solutions, maybe as a part of an initiative to improve offerings – I cannot easily do it if each solution is a document. To do it I would need to find the right files, and I would need to read each one individually. This is not optimal and could take a few hours as opposed to some of the alternative ways of managing this – in an architecture model – we can literally extract such information in a matter  of minutes, because we have a fully relational model.. A collaborative platform such as confluence offers a compromise – it would still require the information to be collated and read manually but at least having things on a common platform makes searching and indexing easier. Its far easier to use an architecture model with documented elements.

Information is point optimized and not often updated.

With Word Documentation the document author should be maintaining documentation that’s used – but it doesn’t often happen. The problem is if someone makes a decision, they tend to document that in the documents they own or know, and not in others. If a product manager changes position, strictly speaking all our Business Continuity Plans, GDPR documentation and other deliverable’s should change with it (if the resource is named by name). I have lost count of the times I have seen failure in this. Business change has to be reflected in documentation.

This isn’t efficient but its the price of using such static manually created information sources such as Word or Open Office documents. Collaborative platforms such as confluence help here – because the work of correcting the shared knowledge base is also shared. A static document can refer to a dynamic system. You need to be careful though because if you do this its very easy to get to a position that is misrepresenting the truth.

If i had a document called “Project Pegasus 2018 End of Year Status” which links to a jira project where statuses of tasks are tracked i can very easily accidentally link to the current task status for 2019.

Word is good when you want to take a snapshot of the current state of affairs, or where you want to share that information with a third party.  For that reason tools such as BiZZdesign’s Enterprise Studio actually have inbuilt mechanisms for publishing documents and the distribution of architecture.

A fully relational model such as a shared repository is much easier to control than when you store information in a document. If you change an element in one place, it automatically changes in others.

So What About High and Low Level Design Document Templates

There are a few reasons I shy away from word templates in architecture design.  This is from ISO42010 – Lets look at it:

ISO 42010 Overview

Stakeholders (The people that get value from architecture – have concerns (issues but also requirements in this context).  Concerns are address by having a view of architecture which is governed by a viewpoint. When we are dealing with complicated architectures we should define solutions that meets the concerns of our stakeholders.

The standard also states that concerns need to be addressed in one or more viewpoints.

Put simply, an architecture solution should be making sure that everyone including the customer, operations, project services, and all the other stakeholders have a solution that meets their needs. Needs change – and depending on those needs, our point of view of the architecture needs to change too because needs of our stakeholders determine the things that need to be emphasized. The architecture design and the structure of work can be very different depending on the story we need to tell – even though in some cases many of the stakeholder concerns are the same.

Learning From Document Templates

In my experience learning by template examples doesn’t work. You can see results of the architecture process but not the architecture process itself. As an example; A template may have a section on process risks. You could choose from your experience to fill in that section – and you may capture a few important things there.  But that set of risks will be much less complete than if you ran through a BPMN risk analysis process. You cannot teach an architect architecture by document examples alone. Stakeholder concerns influence the approach and structure a document may need, and the method is invisible.

Different stakeholders and concerns may lead to radically different documents layouts. In architecture we don’t blindly follow pre-existing structure. We create our own optimal structures.

Copying A Template Example To Fulfill Customer Needs At The End Of A Project

Every time I get asked to do this, I die a little inside. You should do Architecture before, during and after a project . Your Stakeholder needs change or are refined. You need those changes to be included in the architecture. The architecture provides both details of the journey, and decisions made.

Filling out Word templates at the end of a project just to tick a box has very little value. Some people deliver documents then forget about them. Document based architecture needs to be part of a process to provide value. There would be significantly more value if we modeled the architecture design. We can of course use views from a model in our word documents. This is a typical way to communicate with external stakeholders.

The frustration of mindless documentation

Personally, When I am doing design documentation for someone else, Its normally a frustrating exercise. It involves interviewing people, and trying to find answers to questions that have been long forgotten. People make decisions for good reason. If they are not tracked finding reasons for them is hard work.It is not efficient to take this approach . When documentation is after the fact it may check a box for the project. Because its a document rather than part of a model that information may just disappear. If you are building a document template for a solution build in a section to keep track of decisions.

Summing it up…

Templates are good when you need to capture information in a standard way, but that is not the objective of architecture. Architecture is about building new structures, not adhering to existing ones. We have a myriad of processes, frameworks, languages and tools to support that process. 

The reality is that Word remains a good mechanism for outputting architecture to stakeholders, but in a world that changes and expects more lean agile ways of working, we need to use more agile tools to support this.

For documenting architecture methodology, technologies such as word are not optimal, but can work if you have strict process and discipline. You also need to be aware this will cause a major overhead and complexity when trying to optimize architectures later.

Using architecture models, and keeping documentation within them can work a lot better – but a good compromise is to build a model as your primary source of information and then output to work for specific stakeholders as needed.

Understanding Architecture Value

Value is a key focus area of architecture which is often misunderstood. This blog explores this subject..

Value & Professionalism

It has sometimes amazed me how far architecture can be devalued in an organisation. As an Enterprise Architect, I have not only had to show the value to different business stakeholders, but on occasion I have even had to explain it to architects. The reality is, there are a lot of misconceptions around what architecture is and what architects should do. I started to explore expectations in my blog “What is an IT Architect?” because I wanted to get consistent value from my architects.

Getting our stakeholders to understand value can be a hard nut to crack,. They often have their own ideas of what architecture is which normally revolve around technology. I have found the differentiation between a technical specialist and an architect can sometimes be blurry in the minds of our stakeholders. Communication of the different aspects of architecture in a language that stakeholders can understand is essential.

As architects, It’s very important that we work to ensure we are not perceived to be a painful function by our stakeholders. This happens if architects go from meeting to meeting just criticizing other peoples work. It starts with a mindset.

Stakeholders need to understand that, as architects, we are working with solutions and not problems; we must be encouraging by nature and we must take time to express things in terms of positives and growth where possible. We want to be working with our stakeholders rather than against them. Our role is normally to advise – at the end of the day architects do not usually own the business. If we ask rather than tell, engaging our stakeholders with a positive attitude, we can show our value as architects, the value of architecture, and our stakeholders can become the architecture marketing department.

Showing value enables an Enterprise Architect’s stakeholders to look good. This helps us gain stakeholder commitment and makes life easier for everyone at the same time.

For me personally, the best moments come when someone who is not an architect stands up in front of an organization, shows some of the things that we have done together and passionately shows the value that has come through a project, attributing it to architecture not because they have to, but because they genuinely see the benefits, and want everyone else to.

The Reason I Started To Internally Blog

One of the reasons I started internally blogging in my company was that I could not get enough face to face time with stakeholders to express architecture value. I had to show them value by influencing the people around them.

When management has multiple escalations and start to breach service level agreements, they will often start to search for a root cause. Not having architecture is akin to not planning and not managing risk.

In those cases, where poor planning leads to a risk being realised we do not scream “I told you so”. It’s an opportunity to show how as professionals we can help. In those situations normally people are under a lot of pressure.

There are are a lot of techniques we can apply to help identify issues, and when we have a model repository in place, with a competent architecture team we can not only help with solving architecture issues as they are unfolding but we can also put in the steps to ensure those problems don’t happen again. Having a good architecture concerns management process helps with that.

Planning Work

In order to get a baseline of consistency and understanding the blogging helps a lot. Normally I have meetings where I explain things, as we tackle practical problems but if in a meeting i am introducing a lot of key concepts its easy to overwhelm people with the technical side of architecture.

As an example the first time I introduced mechanisms for work planning with ArchiMate. At the backbone, even though i simplified it, still some people didn’t quite follow. The Planning Work With Archimate blog helped. It gave people a reference they can follow at their own pace. It helped me because I can set a consistent expectation.

I think its the most popular blog I have at the time of writing this blog; its been re-blogged and shared a few times, and received a few comments, which is fantastic.

I think the reason for its success is a lot to do with the fact it has clear value. It offers an easy way to use the ArchiMate modelling language to track and define work; which can be challenging – especially if your architects do not have direct line reporting to you.

Capturing the value from stakeholders

To begin with, I think its a mark of any professional that they think about value regardless of what is being done.. It’s a general life idea – if you think about who you are doing things for, why you are trying and try to anticipate needs, the chances are, your resultant work will be better.

Normally at the beginning of a project I am establishing requirements; I sit down with the team and create a series of user stories.

To my mind if you are having trouble defining fully formed user stories for your work, the chances are you need to talk someone and get a little help in understanding the needs of the stakeholders. Most commonly when I see user stories go wrong its because people have missed the bit at the end that speaks of value. It’s interesting to see how often people cannot directly express the value in the things they do; its common to think because value is implied it doesn’t have to be explicitly defined. The problem there is what is an obvious value for one person is not always obvious for another.

In architecture ISO 42010 they give a good ground list for types of stakeholder to consider in our architectures.

Understanding and taking time to explicitly define the needs of our stakeholders is the first step to building an architecture that maximizes the usage of the architecture and its value to all stakeholders.  When we validate an architecture that we have created with a user story we are validating the creation of value.

Why Doesn’t Architecture Always Bring Value?

Not correctly practicing architecture leads to not getting value from it. If an architect starts the architecture work after a project, or views the creation of architecture as a documentation exercise, its normally lost most of its value.  If an architect only concerns him/herself with producing a couple of technical diagrams, again, its lost a lot of value.

Much of the value in architecture is in its application and the process taken to define it. How we decide what appears in the documentation, all the decisions made around the architecture, as well as the needs of all the stakeholders should be managed & documented as a project progresses for architecture to achieve its intrinsic value. 

A Common Problem With Commitment

Because stakeholders don’t always understand what architecture is or how its practiced, it simply isn’t practiced in some cases.

We can have a good group of people that want to do architecture but are not given time. In management terms, architecture is often measured in documents, because these are tangible:

Its easy to see architecture as a documentation exercise if you are working with processes that demand specific types of deliverable, because the emphasis is on the resultant documents. If you write a description of a service it makes sense to plan the service, consider risks, agree the service, and capture the reasons for it. You have to give architects time to plan and think. That thinking time should be spent properly – preferably following some kind of methodology where the thought process is documented.

Even with a management commitment of 70% of an architect’s time allocated to be spent doing architecture, there can still be a fundamental gap if our stakeholders do not understand that architecture process is much more important than these documents.

If architects spend a majority of their time just filling in documents for management, technical writing or building presentations, they will not have time to actually follow methodology and design. Every view an architect does is to manage a concern from a specific stakeholder – therefore you can say every view that is not completed represents a risk that a stakeholder hasn’t been fully considered. Time must be given to do baseline architecture and analysis. It improves the quality of the resultant work and more importantly it ensures not only architects provide value, but their designs do.

A good architecture designed by a proficient architect meets the needs of its stakeholders and shows how it does that – it identifies and mitigates risk. On the flip side, a document that is put together without architecture design is likely to lack good quality. In these cases you will normally see failures in operations – either lower productivity where things are not efficient – or in complete failure of process leading to penalties.

Value In Architecture Modelling

I’ve heard it said a few times that architecture is about drawing boxes; even from some architects. It’s not. 

First the obvious. The tools we use are modelling tools not drawing tools. Most people see an ArchiMate diagram in a presentation and miss the true power behind it – because our views all contribute towards a fully relational model we can easily traverse the model using our tools, and more importantly can use it to easily help management understand the impact of change – at the simple level architects can navigate the model – like shown here – for PRTG Network Monitor:

We can expand out those nodes and see all the relationships, to other elements, and then drill down through those.  We can reuse the elements int he model in different ways and generate views. The more information we put into the models, the more value we get out. Each of the elements and relationships can have its own documentation. Seeing a picture sent in mail is nothing like having the interactive model implemented and available to traverse.

The act of modelling with a proficient modeler building a standard view – nearly always raises questions on how things work, and which things should be connected to other things; these questions open up areas that can easily be forgotten, and its better for the architect to think things through in design phase with stakeholders, than to blindly move onto executing a project. The costs can be very high if part way through a project you need to scrap everything an start again, and architecture can help prevent such things happening.

In addition to all of this we can apply metadata to an architecture model – making it possible to represent a myriad of different interests to our stakeholders, if we take time to model, and use the right information sources; and then use our models to inform and enable our business leaders.

Summing Up The Value Of Modelling

I will sum up some of the value of modelling architecture:

  • Consistent communication – everyone get the same views in a repository and common understanding; there’s a reduction in communication overhead.
  • Enabling Scaling – having consistent communication in a common place makes it easier for us to on board new resources, and for many architects to work together in the enterprise.
  • Reduced time to find things – Navigating through a model from element to element enables us to easily find related information quickly.
  • Can abstract many views from the same model. As you develop some views with relationships, you enable automatic generation of other views reusing the same information
  • Reduction of work – If you rename an element in one view it renames it in all views – in the same way the element documentation is automatically reused.
  • Cost savings – having architecture modeled gives us opportunities to easily see and optimize architecture, as well as to identify risk.
  • Better more reusable architecture – modelling forces us to break down complex tasks into reusable components.
  • Reduced complexity – in a model we can focus on only parts of it in different views to make it easier to consume to different stakeholders.
  • A model develops itself – as it starts to mature using algorithms we can find new relationships rather than have to explicitly state them.
  • Better understanding – at the same time as we establish new components, it normally raises new questions around how things fit together and forces us to think. We can also very precisely and easily model and understand the impact changes in the technology, organization or other architecture layers have on our architecture.

The value of ArchiMate

The Archimate full model shows the different layers that make up ArchiMate. Each layer contains different types of elements in the modelling language – for example we have Business Layer business services, Business functions, business processes. 

The ArchiMate language specifies the different types of elements and the ways that they are allowed to connect. You can see that ArchiMate covers everything from the why (motivation layer), to the what (Strategy, Business, Application, Technology, Physical & Implementation). This enables us to represent how all of these things work in conjunction with each other. 

Following the strict rules of the ArchiMate language forces us to think a certain way – to consider our internal working components and how ex expose them out in different layers. It also has the added benefit of enabling us to derive relationships. A simple example – Owen is related to Max, and Max is related to Christopher – and we could represent this on a model with the association relationships. Even if we do not explicitly say it; because we know these relationships exist the modelling software knows that Owen is related to Christopher. More complex derivations exist – which means that as we mature a model,, it starts to provide value beyond what we directly model.

Summing Up The Value Of Archimate

To sum up the value of ArchiMate:

  • Internationally known standard – each element and relationship has a very specific meaning. using this standard i can take a model from a completely different company and understand its meaning.
  • Multiple layers – breaking down into layers such as Business, Application, and technology, enables us to align to many standard methodologies such as TOGAF, and to easily differentiatiate these different concepts.
  • Better architecture structure – Because ArchiMate has strict rules on what can connect to what, and how elements are used it forces us to think in a more service oriented value driven way.
  • Better connected architecture – Essentially with all the layers together we can answer the questions what, why, when, how, who? The layered approach make it very flexible.
  • Better intimacy with stakeholders – Because we define viewpoints for each of the stakeholders we can provide better value for them and get 
  • Aligns to ISO 42010. Archimate as a language was designed to complement ISO 42010 and make it easier to conform to this standard. ISO42010 introduces concepts of elements and relationships – Archimate creates different types of these elements and relationships, that reduces the amount of work we need to describe concepts.

The Value Of ISO 42010

I speak about ISO 42010 quite often because it lays down the things you need for an architecture to be completely documented.

Everything in ISO 42010 has a purpose and everything that we do not do in there could be represented as a risk.

Its great we do Visio diagrams  with infra and we cover some technology, but for these Visio views to be valid we need to understand the decisions that are made related to them. We need to understand the concerns that different people who need the systems we design have, which includes things like risk. We need to understand how it is that the Visio diagrams produced meet the needs of different people. ISO 42010 lays down a structure that could be used for this.

When you run through an architecture and ask how each individual requirement is being met by the architecture you provide, questions and concerns start to arise. Its better for a single architect or a team of architects to sit down and address them and actually think through the design process, than it is for a project team to start booking lots of meetings with different people.  understanding the needs (concerns) of our stakeholders forms the foundation for formal risk analysis – because the risk is basically recognizing where a need might not be met for some reason. Using a managed approach to architecture concerns provides significantly better coverage of your risks.

When we enter projects there’s often a lot of people asking the same questions – who is doing what, how and where? how will the requirements be managed or realized. Its not supposed to be a project managers role to make those decisions – its supposed to come though someone smart sitting down and creating an architecture design.

Applying Discipline to Architecture

Applying discipline to architecture raises many hard to answer questions that need to be managed. If they aren’t captured and answered at design time they will come up later at some point during an escalation. If you don’t apply a method to your architecture, and do it throughout a project things will get missed resulting in project overheads, delays, and costs in both penalties and incidents.

Applying discipline helps us effectively manage change, and it helps to ensure that issues that may cause problems come up sooner rather than later. 

The alternative to this approach of following methodology is to be surprised – this is characterized for example, by getting part way into a project and realizing the active directory you had build needs to be rebuilt – or discovering that one part of the service you provide will just never work with another part, forcing you to look for some kind of bad designed compromise to meet deadlines.

ISO 42010 essentially gives us an international standard on what an architecture description should include – it enables us to build traceable architectures that meet the needs of our stakeholders, and it does so in a very scaleable way, It enables a consistency of understanding and expectation when transferring architecture from point to point. 

Explicit Value In Motivation Modelling

Up until this point its worth noting that most of the value i have spoken about is relating in generic terms to the benefits given, but of course ArchiMate and some other modelling methodologies allow us to represent values within the architecture going well beyond the generic.  ArchiMate has the motivational layer which is there to show the reason why we do things, and has an actual value element – and of course we can easily derive value normally by just looking at our goals, and outcomes.  Take a look at the example:

The example is a motivation view for an architecture concern. As part of our common practice we might connect values to our goals directly in the model. When you follow the flow of the motivation view above from top to bottom – the values become obvious at the point we get to the goal element – so we model them too.

All architecture should provide value, and in this case we explicitly define it for this requirement (Reduced Capital Expenditure, Reduced Maintenance Cost, Modern Future proof solution).

An implementation & migration viewpoint is focused on how we deliver and meet requirements, and not its value – which is one of the key reasons I also state in addition to implementation and migration, motivational modelling is also a good idea. Of course because this is part of a model we are presented with a powerful mechanism for prioritization workloads – when our management wants to run initiatives to reduce costs for example – we could easily auto generate a viewpoint to show which of our work packages contribute to that, and then we can take a discussion with those stakeholders about re-prioritizing workload in a structured fashion and understand how our other values and goals are effected in doing so.

Summing it up…

Architecture and design before doing things are an essential mechanism for avoiding risk and cost. Architecture is a discipline, and unless you take time to do things before during and after a project you never realize its value. Architects must think and be trained; and they must be given time to run through a design process that applies methodology in order to get the value. If we do this, we will literally save millions of euros in penalties, and will have better more focused projects with a significantly higher success rate. Communication overheads will reduce and better communication will be enabled.

To those who think architecture is only drawing pictures – I would say you do not understand what an architect is, or what an architect does, and would recommend you read ISO 42010; For each part of an architecture design ask the question  “does that provide value, and what is the risk if I do not do that?”

To those that leave architecture to the end of a project, I would say, you’ve lost most of the value architecture could have given you already – because you didn’t see the risks coming fully, may have missed some requirements and you likely had a communication overhead. There’s still some value in doing it so others may follow what you went through and why, and of course anything that adds to an architecture model is a good thing. 

Architecture discipline brings architecture value. I would love to hear from you. 

Architecture Languages, Standards And Frameworks

A discussion on the different architecture Languages, Standards and Frameworks I like to use in conjunction with each other when providing large scale IT & managed services..

My goal in these first posts is to introduce some of the basic ideas and concepts that we will build upon in later posts. I would love to present forward some things such as TOGAF ADM, and the ArchiMate full model, but those things are copyrighted so I can’t present them forward for now.

Modelling Languages

There are 3 industry standard mechanisms I normally use when modelling architecture; and although you may choose to use any other, the mechanisms below give a very good coverage of the different aspects of architecture, so when I talk about the role of architect within our company, I am normally having expectations on the languages I expect an architect to be able to communicate in.

An Example Implementation & Migration View in Archimate
  • ArchiMate – Is a modelling language that allows us to easily bring together different aspects of architecture (Strategic, Business, Application, Technology, Physical, Implementation & Migration, and Motivational). Its important we understand how the business is motivated, how it is realized, how our services are constructed and how these things connect together with both applications and the physical world below it. If we provide consistent architectures and have discipline most ArchiMate tools can provide invaluable business intelligence – I will blog on this further at a later date. Archimate perfectly complements TOGAF. Read more here.
  • BPMN – Archimate is good, but when it comes to understanding how a complex set of tasks are performed with multiple stakeholders BPMN shines – what would be done over several views in Archimate can be done as a single page with BPMN – its designed to model processes that look much more like traditional flow diagrams within swim lanes. I normally align these more in-depth BPMN processes with Archimate – For example in ArchiMate I model the process, with the different business events that align to the BPMN model. and normally assign the different roles and actors – but then the actual steps, happen within the BPMN model. Read more here.
  • UML – Is very good for low level data modelling & class modelling & has been around since the beginning of time. In EA I am tending not to use it too much, because at a high level I can represent data objects & their interactions with Archimate – But UML still has its uses with those who focus more on breaking information down into detail & those with a more application based focus. Read more here.
An Example of BPMN

Project & Architecture Governance

  • Scaled Agile Framework (SAFe) – I like this framework because its relatively simple to use and implement, and provides us a agile development methodology which supports us in a movement towards Dev-Ops, and the continuous delivery of value. Read more here.
  • The Open Group Architecture Framework (TOGAF). A lot of people have said to me that they feel this is a heavy framework that is monolithic and too documentation focused. It doesn’t have to be this way; we can adapt things to be fit for purpose. I think the framework nicely captures the things we need to consider in architecture. Read more here.

For me, a good working practice is actually a hybrid of these two mechanisms – because we need to flexible methodology that covers all the key areas but delivers continuous value.

ISO 42010

This is the international standard for architecture description – and its one of my favorites. When I first read it I was very excited, because it formally said a lot of things I had been standing on my soapbox about for years. It talks about how to describe architecture and covers core needs such as concerns management, and how these need to map onto an architecture solution that considers its stakeholders. Its under a 100 pages long and a recommended read for anyone who is serious about doing architecture.

The heart of ISO 42010

Adding Additional Value

This wouldn’t be complete without mentioning IT4IT and ITIL.

  • IT4IT – Provides a reference architecture for managing the business of IT; at its core is the IT Value Chain, and is very much focused on providing value to the business.. Read more here.
  • IT Infrastructure Library (ITIL) is a set of practices of IT service management – very well know, and very well supported. It can be used in conjunction with IT4IT. I do not know a good resource for free information on ITIL – there’s a lot of material out there though.

Summing It Up…

There are of course many standards we can apply at are equally as good as what I show above, but these are the ones that i found work well together and I like to have implemented together when i have a choice

ArchiMate is designed with ISO 42010 in mind, it’s by The Open Group, who also do TOGAF and IT4IT, so there’s a fair amount of alignment between these. SAFe and TOGAF require a bit of effort to establish good working practices. and IT4IT quite nicely facilitates ITIL which is very much an industry standard.

As always, feel free to comment my post.