Architecture Documentation

Definition

Architecture Documentation

the architecting task the relevant architectures are documented

Classification

As illustrated in the preceding figure, architecture documentation is part of the following inheritance hierarchy:

• Type: Concrete
• Superclass: Task
• Subclasses: None

Responsibilities

The typical responsibilities of the architecture documentation task are to:

• Document the architectures:
  • Business enterprise architectures.
  • Application architectures.
  • Framework architectures.
  • Reusable component architectures.
• Improve the communication of architecture information.
• Enable the efficient evaluation and reuse of architecture information.

Preconditions

Architecture documentation can typically begin when the following preconditions hold:

• The business strategy team, technology strategy team, or architecture team have been adequately:
  • Staffed.
  • Trained in architecture documentation.
• Content and format standards exist for the relevant architecture documents.
• Templates exist for the relevant architecture documents.
• Content (e.g., style, logical and physical architectures, mechanisms) exists to be documented.

Completion Criteria

Architecture documentation is typically complete when the following postconditions hold:

• All relevant architecture documents are complete, have passed evaluation, were baselined, and were accepted by the customer representative.

Steps

Architecture documentation typically involves the following teams performing the following steps in an incremental, iterative, parallel, and time-boxed manner:

• Business Strategy Team, Technology Strategy Team, and/or Architecture Team:
  • Read the appropriate content and format standards.
  • Identify and obtain the appropriate documentation templates.
  • Create the initial documents by instantiating the associated templates.
  • Fill in the front matter and introduction sections.
  • Either manually or automatically enter the contents of the main sections into the appropriate templates to create the architecture documents.
  • Fill in the appendices including all major issues, TBDs, and assumptions.
  • Generate the associated tables of contents and tables of figures.
  • Informally evaluate these documents:
    • Against their content and format standards.
    • Against their inspection checklists.
  • Iterate and maintain the documents as necessary.

Techniques

Architecture documentation typically can be performed using the following techniques:

• Documentation Standards(for content and format)
• Documentation Templates
• Inspection Checklists(for informally evaluating the documentation)
• Language Standards(such as XML, HTML, or MS Word, in order of preference)

Work Products

Architecture documentation typically results in the production of all or part of the following architecture work products:

• Business Engineering architecture documents:
  • Business Object Model,
    
  • Business Process Model
  • Business Organization Chart
  • Application Business Case
  • Application Strategy
  • Relationship Strategy
  • Business Architecture Document
  • Business Transition Plan
  • Reuse Strategy
  • TechnologyStrategy
• Application Development architecture documents:
  • Contact Center Architecture Document
  • Data Center Architecture Document
  • System Architecture Document
  • Information Architecture Document
  • Software Architecture Document

Guidelines

• Using technical writers instead of architects to produce and maintain the documents often results in higher quality, lower costs, and fewer schedule overruns.
• Documents can be created and maintained manually or else generated automatically by tools from appropriate databases.
• If documentation is relegated to the end of the activity rather than being performed iteratively, incrementally, and concurrently with the other architecture tasks, the probability that the documentation will never be completed increases as well as the risks to the endeavor.
• Architecture documentation should be an ongoing task as the contents are iterated.