2. Requirements for Software Architecture Documentation

This section outlines the requirements and goals that shall be met by architecture documentation.

These requirements are quality goals, that means achieving them means effecting compromises: Many quality goals negatively affect each other, so that a global optimization is rather difficult. For exam-ple, accuracy and up-to-dateness of any documentation has negative impact on maintenance cost (as it takes more effort to keep the document current).

The most important quality goals for architecture documentation are:

  • Maintainability
  • Understandability
  • Accuracy
  • Up-To-Dateness
  • Transparency
  • Stakeholder-Orientation

Efficiently Maintainable

Due to significant maintenance costs associated with large-scale documentation, architecture documentation aims at keeping this effort in balance with understandability, accuracy and up-to-dateness.

Maintainability of documentation is affected by (at least) the following factors:

  • Amount of documentation (shorter docu is easier to maintain)
  • Redundancy (repeating information sometimes helps readers to avoid jumping around in docu-ments, but increases maintencance effort)
  • Established standard structure: See section 2.2 on understandability.
  • Tools used: Appropriate tool support can significantly reduce overhead.

The following steps shall be taken to support maintainability:

  • Limit the amount of details (e.g. do not duplicate information that can be easily taken from sour-cecode), especially:
    • Architecture documentation is no replacement for inline code documentation, but shall be supported by a best-practice approach in sourcecode documentation.
    • Only „architecturally relevant“ details shall be included.
  • Stick to the established structure, so the „location“ of documentation changes are simple to de-termin.

Easily Understandable

A contracting entity needs to keep a thorough understanding of the architectural structure of , over regular releases Understandability of documentation is affected by (at least) the following factors:

  • Ease of Navigation & Retrievability: These are achieved by
    • relying on established, standardized and well-documented structure, so that both readers and writers know in advance where to find or file certain information (e.g. runtime scenar-ios are always documented in chapter 5).
    • Keeping an up-to-date index of keywords and topics, for quick retrieval of information (supported by a project or system glossary).
  • Clarity & Style – both of which are subjective matters.
  • Absence of surprises to readers. For example, the reader shall find every piece of information at exactly the location where it’s expected.

Accurate and Up-To-Date

Information contained within the architecture documentation has to be both accurate in the sense of “cor-rect”, so that stakeholders (developers, system- and software-architects, testers etc.) can rely on this information. Accurateness of documentation is affected by (at least) the following factors:

  • Every fact given in the documentation is currently correct. All changes in the system shall be re-flected in the documentation in a timely manner (when the change occurs). Every change has to be documented not later than release-time.
  • All important facts are given in the documentation. For architecture that means „completeness“ without „exhaustiveness“. See „Maintanability“, section 2.1.
  • Missing information is marked as such. When crucial information is missing, both reasons and time of remedy shall be given.

Accurate with respect to Modifications, Changes and Releases Changes in the system (in its requirements, architecture and implementation) shall be reflected in the respective documentation. There shall be an change history, so that changes can be tracked with appro-priate effort (this is a tradeoff between accuracy and maintainance-costs).

Transparency

A contracting organisation shall be able to really understand structure and implementation of , even in an outsourced development model, with an appropriate audit effort . It shall audit every release to acknowledge that

  • The required changes have been incorporated, both functional and nonfunctional. This can be done by acceptance testing.
  • The system structure (its architecture) has been modified appropriately: Only those parts of the system have been modified that really needed modification due to the current requirements.
  • The implementation changed according to the the changed architecture. This could be done by inspecting sourcecode artifacts or calculating sourcecode metrics.

In particular shall a contracting organisation be able to detect inappropriate or unsuitable changes in both architecture and implementation with low (appropriate, see footnote 2) effort.

A subgoal of transparency is traceability: It shall be possible to trace requirements into the respective solution decisions: Where and how did a specific requirement affect the architecture and implementation? Traceability in architecture documentation is achieved by transparency and adherence to corresponding acceptance criteria (especially those described in the architecture criteria catalogue).

You Only Know it’s “Good Enough” when your readers tell you so!

Readers of architecture documentation shall regularly be questioned for improvement suggestions and the perceived usefulness of the documentation, in order to reflect the documentation maintenance in-vestments.