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.
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:
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.