The Trouble with Documentation

Developing good quality architectures is the what the Architect is there to do and there are many good architects who can do this. What often stops them from being great Architects is the communication of their thoughts and ideas. In fairness this is an incredibly difficult thing to do as there are usually many ways of describing the solution and, most importantly, many different readers or stakeholders.

The key point is that documentation is fundamentally about communication. The Architect has a mental model which they need to get into other people’s heads. The medium to do this is documentation as it provides a way of doing this in a communicable and durable way.

What this means is that the first step to good documentation is understanding your audience, also known as your stakeholders. This is where the trouble becomes apparent. What you need to communicate to a software developer is not the same as that for a network engineer. Then there are project managers, technical design authorities and of course senior executives

So how do we resolve this; how do we produce one set of documentation which adequately describes our solution and also meets the needs of our different stakeholders?

An approach which is gaining ground in the architecture world is that of views. Essentially this approach says that while there is only one solution, there is more than one way of looking at it. Some people also talk about the concept of filters or lenses as ways of distinguishing between different views.

The first step in this process is to list out your stakeholders; not all of them, just the ones who you need to communicate with. Then try to understand what they are looking for, what do they need to understand? You can then shape your deliverables around their needs rather than yours.

The approach is not perfect and takes some getting used to, but the outcome is something that is far more valuable, useful and hopefully appreciated!

If this sounds a little theoretical then there are quite a few resources to help you get started.

The Open Group Architecture Framework has a whole chapter on architecture views which can be found here.

The SEI have embraced the concept of views and have a template plus other information here.

Some of the SEI team have also produced a book on the subject which is available at Amazon.

There is also an ISO standard which much of the above but unless you are really interested in standards the above resources will be more use. The page on Wikipedia provides more details

This entry was posted on 10/03/2008 at 08:48 am and is filed under How to Architect. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response or trackback from your own site.

| Print