What Are Architecture Documents For?

I recently had a discussion with a colleague about what the real purpose of architecture documentation is. The simple answer of “documenting the architecture” seems unsatisfactory to me – “what is the point in that?” I think. My response to him was that architecture documents are for recording (and communicating) architectural decisions.  This is part of my overall focus on the value of our efforts in architecture. What is important about architectural documentation is that once the architect or architects have made an architectural decision you write it down, so that the decision isn’t lost or forgotten, and so people who weren’t involved in the discussion can go “somewhere” to find out what the decision is. The document is then added to with each subsequent decision, becoming the overall record of all of the architectural decisions of the piece of work – that is to say,  its architecture. At the start of the project the decisions are bigger and more important. As the project goes on, the importance, scale and scope of the decisions decreases.

An important consequence of this view is that architectural documents are living documents. They aren’t finished until all of the architectural decisions are made – something that in my experience happens very late in the life of a project. I don’t think of this as a problem for my view, instead it is a strength. In reality architectural decisions keep on being made during the life of a project. If they aren’t recorded in a document that is understood to be a living thing, then they are usually lost or forgotten, to the detriment of the success of the project, or anyone who comes later trying to understand what was done and why.

Some people might object that the point if architectural documents is to describe the architecture, so that this can be passed to the component designers so they can build their parts of the overall project. And that this can’t be done until the architecture is complete. While there is some truth to this point of view, my experience is that completing the architecture” requires complete information, about the requirements, objectives, constraints for the architecture, as well as information about people, process and technology that will be used to implement the architecture. In practice if we waited until we had all of that information before completing the architecture then most projects would never get very far. I have rarely had the luxury of having a project that had enough information to complete an architecture up front before designers or technical experts needed some input.

I don’t think that these views are diametrically opposed – just a difference in emphasis. My emphasis is on why we document (to communicate, to record); on what is being communicated and recorded (decisions); and on the dynamic, living nature of working in a project environment.


3 Comments to “What Are Architecture Documents For?”

  1. Great post. This is something that comes up from time to time with those who argue that the code is the documentation. In truth, the code documents what the architecture is, but fails to document why. You need something that captures that why and it needs to be accessible to a far wider audience than the code.

    Regarding the “unfinished” aspect, IMO the architecture isn’t “finished” until the day you pull the plug. Until then, it’s a work in progress.

    • “the code is the documentation”, ouch! when I ask most coders where their documentation is they generally point at their head and laugh. Agree with your comment, and agree on this post

    • Hi Gene and Simon, thanks for the feedback. I’d qualify the comments about “the code is the documentation”. Firstly, I believe that architecture includes the motivation (it is an essential part of the architecture) and code can’t capture that, Secondly, part of the point of architecture documentation is to communicate the architecture to diverse audiences, the most important of whom (e.g. the business) cannot read code. Lastly, that statement only applies to classic software architecture. I can’t remember the last time I was involved in a project which only used bespoke software development. With most solution and enterprise architecture one is deploying multiple COTS software and hardware products, the network is a part of the solution, configuration is important, and the people and processes are an important part of the solution too. Code can only document a small part of an overall solution of that sort.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: