Link: http://dougnewdick.wordpress.com/2013/07/26/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.
