Tips for Creating Domain Architecture Documentation

Domain Architecture documents are one of the most widely created, and probably the most misunderstood, of the various EA deliverables an EA team might have in their document repository.  As we visit EA teams we often discover these documents in various states of disrepair, from perpetual draft, to complete but out of date, to a minimalist listing of product standards, to over-written tutorials on topics long ago commoditized or no longer relevent.

We were recently asked by a client to clarify the latest thinking on these documents.  Are they still relevent, who are they for, and what value to they deliver?   The short answer is that the thinking on domain documentation has not fundamentally changed, though it has matured a bit.  The focus these days is on determining what that documentation is for, who uses it, and what other documentation is required in the set of deliverables an EA team could produce.

First, a couple of caveats: When deciding what documents to create, the most important thing is to make sure you will be able to maintain them.   Also, it is important to understand who the users of each document are and to structure accordingly, to understand the relationships between different deliverables, and to have an appreciation for the absolute and relative value of each deliverable.  We are biased to invest heaviest in documents that are prescriptive for external stakeholders, while putting tangible (though less) relative value on deliverables used internally to the EA group (and invest more when they are foundational to other higher-valued deliverables).

Domain documentation is one of those areas that cross a couple of boundaries of the caveats just described, providing value at different levels:

1)      The primary audiences for technical domain documentation is the EA group itself and its extended SME community responsible for the asset categories contained in the specific domain.   As such, in and of themselves any given domain document has somewhat narrow prescriptive appeal to include primarily those that, for example, select, operate, maintain “platforms”, “networks”, “middleware”, etc.

2)      The primary content of domain documentation is design principles, categories, standards, products and configurations, including specific use-case descriptions for when and how to select them – as we have historically described.

3)      Taken together, the collection of technical domain documents contain “parts” or “building blocks”, and through the use-case scenarios and design principles, become components of higher-order constructs like “patterns” (e.g. infrastruture or development) or “platforms” (e.g. application).  These patterns deliver higher-order value, consumable in the direct construction of solutions.  The domains, in turn, have foundational value because they inform the consistent creation of the patterns as common building blocks.

When creating traditional Technical Domain Architecture documents, many organizations opt to organize around a Technical Reference Model (like TOGAF’s TRM), create a product lifecycle (standard, obsolete, research, sunset, etc.) model in spreadsheets, or create product/standard roadmaps (as we have discussed in the past).  These lack the degree of detail of domain architectures, and frequently do not include helpful use-case information.  They tend to be product/release-specific and less prescriptive to stakeholders other than the asset owners.  Nonetheless, they do tend to satisfy the audience of consumers that want answers to “what product do I use?” questions.

Our bottom-line recommendations:

  • Do not over-invest in domain documents, yet they serve an important purpose – foundationally, for the EA team, and for SME asset owner communities.
  • Make sure the authors are creating tight, prescriptive deliverables geared to the specific stakeholder community.
  • Make sure that the authors are not writing lengthy tutorials – these are not educational documents.
  • Recognize that the creation of higher-order patterns, etc. will absolutely require cross-domain collaboration, so it is best to avoid compartmentalizing domain document development to just those knowledgeable about the subject matter.
  • Also, realize that different domain documents will, from the very nature of the topic (revolutionary, or commodity), require different levels of specification and detail.  Don’t try too hard to make them all exactly equal.