Documenting An Architecture Model

There are many considerations to make when documenting an architecture model. This blog speaks of some things to think about when documenting elements and relationships.

When I am speaking about documentation I am primarily talking about the documentation fields that are available with different modelling tools for documenting elements and relationships.

On Monday I posted about designing architecture through document templates. Keeping on a theme of documenting things, I wanted to talk about some of the things to consider when documenting within a model. Although I primarily talk about Archimate here, similar considerations must be taken when documenting any kind of relational model.

Elements & Relationships

ISO 42010 talks a lot about elements and relationships, and as I have said before, Archimate extends the concept.  The image above shows two business objects connected by a relationship.  The shapes in ArchiMate are elements – the connecting lines or arrows between them are relationships. 

We have said before that our modelling tools are creating architecture models and not pictures and that is important to understand when it comes to documenting elements. Each element is a building block that may be in many different  views which means when we document an element the focus of the documentation is the element itself and not its connection to other objects. Consider the diagram below:

Part of a very simple Service Realization View

We have an application component MySQL. Within this view we could document the element by saying:

MySQL provides back end services for our Apache application.”

In a word document that would be perfectly fine. In a model this would be bad practice for a few reasons – I have some points to make here:

  • Firstly, If we were to use the MySQL element in another view, such as a realization view for a PHP application service, although the statement above would still be true in the first view it would not be contextually relevant to the PHP realization view. 
  • Secondly – We have already expressed the documentation in a relationship on the view – the arrow between MySQL and Apache – It says MySQL serves Apache.  This relationship documentation would actually be a better place to put our documentation text although, as we said, its not needed.
  • Thirdly – If we find it relevant, to telling the story of the entire picture, we can actually place the documentation as part of the view – although it would be better for the view documentation to provide an overview of what the whole picture is about for the audience, rather than focusing on the minutia that is in each and every documentation element. We can also document each individual folder in a model, as well as applying documentation to the model package itself.

Deciding when you need more elements.

If you consider the example with MySQL again, we could provide a description of what MySQL is such as:

MySQL Server is a relational database management system developed by MySQL AB. As a database server, it is a software product with the primary function of storing and retrieving data as requested by other software applications.

…this is pretty good text because it explains what the element is and it could be reused across multiple views – however there’s another thing to consider. The relationship between MySQL AB and MySQL.  When writing something like that I ask myself is there any value in separating the vendor from the application component. I would say yes, its handy from a vendor management perspective – so on the view I showed above you can clearly see the vendor, and it only takes a few seconds for me to generate a view which would show all the applications that Microsoft are related to.

I would probably allow the definition above to be used in many cases – because even though it talks of the relationship between MySQL and MySQL AB, I think its OK because that relationship between product and vendor is very unlikely to change. If we were talking about a relationship that was more dynamic in nature I would probably redraft the definition.

How much should we document?

I would consider documenting all elements, and most relationships when fully modelling something, as well as documenting the view as well, to tell the story of the view and a little of the views intentions to its stakeholders.  The thing to remember here is not everyone knows what you do and what is obvious to you may not always be obvious to all readers of your view, or why relationships exist.  A colleague of mine who works with architecture in the defense industry was telling me he asks that all elements and relationships are documented as a rule of thumb for exactly that reason.

Its important that we get our balance right – we do not document for the sake of it but the view is providing the audience a story and all the elements and relationships within it form part of that story (I talk about this a little in my blog Improving Archimate Model Quality). Because Archimate provides some correspondence itself I will normally read out all the relationships on a model to myself. For example – “Owen is assigned to the role of Enterprise Architect”. I then ask myself does that say enough. Do I need to tell the audience why? If the answer is no, then I probably will not put any documentation in that relationship – because the relationship type (assignment) says enough by itself.

Asking For Help

I like to peer review views that I create, and get another architect to tell me the story of what my view says – a fully documented view I will also ask questions on just to see if its intuitive enough to enable the architect to answer.

Within my architecture domain I encourage all my architects to spar this with me, and in some cases i will give a view to a non architect too, just to see if they can figure things out.

Effective communication is key – if you are finding it hard to find the balance, sharing in a peer review can be a good way forward.

2 thoughts on “Documenting An Architecture Model

  1. Might be a dumb questions. When you speak of documenting, do you mean using Documentation field/element properties as the place to store said documentation Or are you thinking more on the lines of visual notes(Note elements) ?

Leave a Reply