So, sitting there and trying to collect the facts spawning out of the pages into my brain, hoping to puzzle together an picture (the picture of software), one thought flashed in my mind: can architecture documents tell stories - and even should they ? (For those who read my last post, lets assume the Constructible Hypothesis is true).
Technical Systems are built from human beings (Well, at least at the moment) Because humans evolve day by day with growing experience causing shifting look at things and moving attitudes these technical systems have history. Humans learn about problems, learn about solutions and in consequence learn to evolve methods and tools.
But not only the creator has history, also the environment = the source of the problems is non-static. Customers have new wishes, technical or environmental constrains change. All this together make it undeniable that a technical product has history. For example, many things on modern ships have their roots in the old wooden sailers. The instrumentation of the airplanes are frozen history of aviation construction.
There is a move citation (I think it was "Big Trouble in Little China" with Kurt Russel): "Thats like all things begin: small and decent". Yes ! This is the power of knowing history: the first versions of things are often simple, not elegant or efficient, but small enough to not covering the basic idea behind a solution. Or better: in the beginning of technical things the intention of the architectural elements will be visible. Going back in history means going to the core part of a technical mechanism, the will of the creator. Going back means to get insight into the basic idea of things.
But there is more. We said technical things evolve. But they evolve not without reason. If technical properties or functions being added, that should be done because of a changed requirements ! So history should tell you a story about sound decisions, why this function or this effect added to the system, and why the old system was not good enough. Again, evolutionary steps have an intention behind them (hopefully !). This is far from trivial, so many team members don't know why software module x or parameter y were added. Look how many things are introduced and killed later on because the knowledge of their introduction got lost.
Now, knowing the history of a technical product seems good. But the question is now can an architectural documentation tell the history ?
Please don't think at the huge version trees of such tools like CVS or Subversion etc. It is not practical to write down a full history log, of course not. But if you see an technical product as a chain of design decisions, controlled by intentions, it might be more clear how to document:
show the basic problem and the basic idea, and show the most important intentions from the historic sequence of intentions shaping the architecture as it is today.
Showing intentions is not necessarily complicated: well chosen names and wording can suggest what the basic idea or problem was. Also, arranging the document along an level of detail gradient can have the effect to present the reader a time trip. AND: show the associated problems !
But my statement is this: just nailing down an architecture as it is in front of you is often not enough. Such documentation may be useful for rebuilding technical things only (schematics for example), but not to understand them. Or to say it much easier: show the human factor in the architecture.
I know, this is no precise plan how to write documents. This may be part of a later post :)
