Architecture standards: Documentation

This is the third posting in a series on architecture standards. In the previous posting we presented some basic terminology. Most importantly, we distinguished between standard rules, and standard components. In this posting we pick up the thread and zoom in on the documentation of standards. In order to do so, we kick off this post with an analysis of how/ where standards are used, and “derive” a template from that.

Using standards in architecture work

Having a (well documented) library of standards may look impressive, but need not be very effective by itself. Indeed, we have seen organizations with close to 5000 pages of architecture standards! This didn’t even cover security standards and infrastructure standards in their full depth yet..!  

Impressive indeed, but barely usable in practice! During an engagement at this organization, we learned that standards were too long and fuzzy, that nobody really knew all the standards and that governance was hard to say the least.

Since architecture helps in effectively designing and transforming organizations, standards tend to be used to either (a) help architects to their work – that is, they pertain to the process of doing architecture, or (b) help  architects in making and implementing effective design choices. Therefore, the way standards are documented should be tailored to being of use in (change related) projects.

Requirements for standards documentation

In our previous posting we already touched upon the “deck of cards” approach to standards. This deck of cards is – in a matter of speaking – the “bible of governance” and should therefore be well structured, accessible, and up to date.

Standard rules and components should be separated from their associated specifications and configurations for reasons of stability, maintainability etc.  This implies that the first requirement for standard rules and components should be that they are extremely to the point. In practice we have found that a maximum of two pages is generally enough. This requirement does not hold for specifications and configurations: here we document all the necessary details (controls, patterns, scenarios etc.) that projects need in order to get the job done. Indeed, we have seen specifications as large as 40 pages!

In a way, requirements for standards documentation are similar to those of architecture principles in the TOGAF standard (see e.g. our earlier series on TOGAF):

• A standard document should contain a rationale (why did we decide to make this a standard) as well as a SMART statement of what is actually being standardized.
• We strongly recommend that it should be made explicit how governance will take place: who will check what, and when in order to make sure that the standard is followed? This will provide much-desired clarity for projects actually using the standard.
• Since we have different types of standards, relations between standards must explicitly be documented. This means, for example, that standard rules contain “pointers” to associated components and specification.
• Last but not least, the usual “meta data” should be in place: when does the standard expire, who owns it, what domains does it belong to, etc.

If you’re interested in templates for standards, please get in touch via E-mail. Our contact information can be found at the bottom of this posting.

Document management

Different projects touch upon different aspects of the enterprise. Therefore, different projects need different sets of standards or a different “hand of cards from the deck” so to speak.  The selected set of standards is the basis for governance later in the project lifecycle. In order to support this process of selection, it is recommended to document as part of the standard the situations or scenarios in which the standard is applicable. E.g. enterprise standards for presentational styles are applicable in every project where web pages are developed. It is also highly recommended to keep track of which set of standards each project is expected to follow. 

In practice we have found that a simple DMS can be very effective for managing both the individual documents for each standard (i.e., keeping version + change logs) as well as the issue of tracking compliance of projects.

The lifecycle / evolution of standards is discussed in posting 5 of this series. Governance is discussed in posting 6.