Architecture Definition Document

Recently, I have reviewed the TOGAF 9.1 framework. One topic (of many) that interests me is what content is required / recommended in the Architecture Definition Document and the Architecture Requirements Specification. I find that the details are spread out in the TOGAF 9.1 documentation. I will start with the Architecture Definition Document in this blog posting.

According to the TOGAF specification, the Architecture Definition Document is “the deliverable container for the core architectural artifacts created during a project and for important related information”.

Furthermore, the Architecture Definition Document is

“a companion to the Architecture Requirements Specification, with a complementary objective:

  • The Architecture Definition Document provides a qualitative view of the solution and aims to communicate the intent of the architects.
  • The Architecture Requirements Specification provides a quantitative view of the solution, stating measurable criteria that must be met during the implementation of the architecture.”

Let me state this again …

  • Architecture Definition Document provides a qualitative view
  • Architecture Requirements Specification provides a quantitative view

The Architecture Definition Document is first created in Phase A: Architecture Vision. Section 36.2.3 of the TOGAF specification states that the Architecture Definition Document can contain the following contents:

  • Scope
  • Goals, objectives, and constraints
  • Architecture principles
  • Baseline Architecture
  • Architecture models (for each state to be modeled):
    • Business Architecture models
    • Data Architecture models
    • Application Architecture models
    • Technology Architecture models
  • Rationale and justification for architectural approach
  • Mapping to Architecture Repository:
    • Mapping to Architecture Landscape
    • Mapping to reference models
    • Mapping to standards
    • Re-use assessment
  • Gap analysis
  • Impact assessment
  • Transition Architecture:
    • Definition of transition states
    • Business Architecture for each transition state
    • Data Architecture for each transition state
    • Application Architecture for each transition state
    • Technology Architecture for each transition state

The above list should be your starting Table of Contents for your Architecture Definition Document. You will need to add content to those sections in order to finalize the document.

The Architecture Definition Document should also contain sub-sections for:

  • Baseline Business Architecture
  • Baseline Technology Architecture
  • Baseline Data Architecture
  • Baseline Application Architecture
  • Target Business Architecture
  • Target Technology Architecture
  • Target Data Architecture
  • Target Application Architecture

That is, you could be these under each state of the architecture model.

Phases B, C, and D add documentation to the applicable sections in the Architecture Definition Document. The documentation is the output of the steps in each phase. For example the steps in Phase B: Business Architecture are:

  • Select reference models, viewpoints, and tools
  • Develop Baseline Business Architecture Description
  • Develop Target Business Architecture Description
  • Perform gap analysis
  • Define candidate roadmap components
  • Resolve impacts across the Architecture Landscape
  • Conduct formal stakeholder review
  • Finalize the Business Architecture
  • Create Architecture Definition Document

As I indicated earlier, similar steps are noted for Phase C: Information Systems Architecture and Phase D: Technology Architecture.

This is where it gets confusing (at least for me). Documentation is created from each of these steps in the phases. Most of the documentation is added to the Architecture Definition Document. Some of the steps create documentation that is added to the Architecture Requirements Specification.

The last step is Create Architecture Definition Document. The following sub-steps are performed:

  • Document rationale for building block decisions in the Architecture Definition Document
  • Prepare the business sections of the Architecture Definition Document, comprising some or all of:
    • A business footprint (a high-level description of the people and locations involved with key business functions)
    • A detailed description of business functions and their information needs
    • A management footprint (showing span of control and accountability)
    • Standards, rules, and guidelines showing working practices, legislation, financial measures, etc.
    • A skills matrix and set of job descriptions
  • If appropriate, use reports and/or graphics generated by modeling tools to demonstrate key views of the architecture. Route the document for review by relevant stakeholders, and incorporate feedback.

Basically, these sub-steps are adding more documentation to the Architecture Definition Document. The last sub-step requires a review. Thus, it is not enough to add documentation.

But don’t forget to add all of the documentation from the previous steps within the phase! The following documentation is added to the Architecture Definition Document from the steps in Phase B: Business Architecture:

  • Baseline Business Architecture, if appropriate
  • Target Business Architecture, including:
    • Organization structure — identifying business locations and relating them to organizational units
    • Business goals and objectives — for the enterprise and each organizational unit
    • Business functions — a detailed, recursive step involving successive decomposition of major functional areas into sub-functions
    • Business services — the services that the enterprise and each enterprise unit provides to its customers, both internally and externally
    • Business processes, including measures and deliverables
    • Business roles, including development and modification of skills requirements
    • Business data model
    • Correlation of organization and functions — relate business functions to organizational units in the form of a matrix report
  • Views corresponding to the selected viewpoints addressing key stakeholder concerns

Thus, there is a considerable amount of documentation that is added to the Architecture Definition Document in this phase! This is what I found a little bit confusing. You must look through all of the steps to determine the documentation to add to the Architecture Definition Document and the Architecture Requirements Specification.

The steps, sub-steps, and documentation are repeated in each of the next phases:

  • Phase C: Information Systems Architectures – Data Architecture
  • Phase C: Information Systems Architectures – Application Architecture
  • Phase D: Technology Architecture

I could list all of the required documentation for each of steps in each of these phases here; but it becomes too lengthy (and you can read it for yourself in the TOGAF specification).

Now we enter Phase E: Opportunities & Solutions. This is where we finalize all of the documentation that is in the Architecture Definition Document. The following additional sections (with content) may be added:

  • Transition Architecture, number and scope as necessary
  • Views corresponding to the selected viewpoints addressing key stakeholder concerns

Now the Architecture Definition Document should be reviewed (again) by the applicable stakeholders and considered final.

Are you done? No, of course not!

You should have reviewed your Architecture Vision. Confirm that the Architecture Definition Document is describing the same outcome as the Architecture Vision. If not, you have a problem! The Architecture Vision was communicated to your stakeholders at the very beginning. You may have even provided a summary version of the draft Architecture Definition Document.

You should also be tracking the reviews and versions of the Architecture Definition Document throughout the ADM process.

Final edits to the Architecture Definition Document are completed in Phase F: Migration Planning. You may need to add a Transition Architecture State Evolution Table. Also, you may need to update details on the implementation if there were changes to the implementation approach because of the Transition Architecture. Now you are done – assuming the document is reviewed and approved.

You can download a copy of an Architecture Definition Document here: http://www.isaca.org/Groups/Professional-English/enterprise-architecture/GroupDocuments/TOGAF%209%20Template%20-%20Architecture%20Definition.doc

I like this template because each section has a purpose, description, and quality criteria. There are even some content examples. Here is a screenshot of the Table of Contents:

TOC1

You can also download templates from TOGAF here https://publications.opengroup.org/i092

The Architecture Definition template has the following Table of Contents:

TOC2

I prefer the first template. I would add sections from the TOGAF template and update the Table of Contents. I may still need to add sections for Transition Architectures and Views.

In conclusion, I have a better understanding of the Architecture Definition Document. I also have a sample template that I can use.