Mike Walker has a nice blog post and links regarding the documentation of architecture. He talks about how the IEEE 1471 recommendation is being incorporated into an ISO standard with specific applications into enterprise architecture. I see this as a great step in advancing the craft of enterprise architecture. Related to my previous post on EA notation, the importance of clear EA documentation cannot be understated.
From IEEE 1471 (and Documenting Software Architecture) I have consistently advocated for certain principles in documentation. The first is one diagram is insufficient to fully describe an architecture. One needs to produce multiple views based on their audience and specific business problem being addressed. The CxOs don’t care about seeing the detailed SOA call trace over HTTP; they want to see OpEx reduction in their application portfolio. Second, a picture alone is insufficient. Now, when we’re presenting to stakeholders we only show the picture (the view). But we should also include supplemental documentation with an “element catalog” that fully describes each box and line in the diagram. It goes a long way to making the document more valuable outside the presentation context.
What techniques do you use to document your enterprise architecture? Do you follow (parts of?) IEEE 1471? Or do you have other approaches that you incorporate? I invite you to chime in here or over at Mike’s blog post.