Tips for the architecture documentation process

In IT architecture documentation serves several purposes. While the younger generations seem to ignore the written word and drawings, it remains an important tool for communication in many organizations. Not only between the architects and the developers, also between the sponsors and the architect or architecture team. And let's not forget the remaining stakeholders.

The challenge here is to create a controllable process without putting to much limitations on the creativity needed during the creation of the architecture. So first of all you shouldn't try to implement a process. Confused? Read on.

What really matters is the documentation trail and approvals. Haven't you seen those documents labeled with statuses like: draft, concept, preliminary, to be reviewed, final or any arbitrary combination of those labels? Were you immediately clear AND sure where you were standing with the documentation? My experience so far is that nobody takes notice of the status, as there are no universal accepted values related to these labels. In other words: useless. Oh, by the way, quite a few implemented document management systems are dysfunctional within the IT organization.

You don't need to look far for a solution. You just take version management and apply it to documents as software engineers do with code. But don't go down the road of releases with mayor, minor versions with revisions. That complexity is not needed here. A simple release and version nummer in the format release.version is sufficient (e.g. 0.3, 1.1).

And now the "trick" to get to a documentation trail and approval without really trying to implement a process.

Give version numbers a meaning (or status if you will). Be rigid with the definition, don't tolerate diversions. It is amazing how quickly word of mouth will spread, the acceptance of the "process" is almost viral. We started this at the corporate level in a large organization with several autonomous divisions and within a few months all people involved with architecture documentation were aware and acted accordingly. And this was achieved without any systems and software for document management! Just "free flowing" documentation, usually shared with e-mail. Oh, it helps to ignore the whiners.

Based on our experience give the following value (read meaning or status) to a version number.

x.1 - x.4	Internal versions for the team who creates the documentation
x.5	First version to be shown to the lead architect in the applicable domain
x.6 - x.7	Additional internal versions
x.8	Version to be formally reviewed by the architecture board (or whatever group is responsible for signing off on the content)
x.9	Version to be approved by the sponsor (e.g. CIO, business management)
x+1.0	Final (approved!) version

x is the release number and should start with 0.

Those who observe closely notice that the version number also represent the approximate percentage of completeness. 0.5 is 50% ready, 0.9 is 90% ready, etc.

That's all! Enjoy the results.

© Peter Bodifée 2008. All rights reserved