Tech Standards / ´╗┐Architecture Documentation

Architecture Documentation

Architecture documentation, also known as software architecture description explains practices that are used in architecture of a software system but it can also refer to the outcome of application of the very same practices. Thus architecture documentation can be classified into:

Purposes of Architecture Documentation

Architecture documentation doesn’t only deal with technical aspects of the system. Some of the issues discussed by architecture documentation are technical in nature but many are also intended to help architects, end users and other involved in the process of development and utilisation of software architecture.

The main purposes of software architecture description include:

Organisation of Architecture Documentation

Architecture documentation must explain practices used by software architects during construction but it also must address issues relevant for stakeholders including system owners, end users, system engineers and others involved in the development and utilisation of the system. The documentation is often organised into architectural models which in turn can be organised into several different forms including texts, diagrams, drawings, etc. in order to facilitate communication with a wide audience as well as cover a wide range of architectural concerns. For practical reasons, architectural models are often organised into different views with each addressing issues relevant for different audiences.

Architecture Documentation As a Breed of Design Document

Architecture documentation can also be defined as one of three breeds of design document, with the other two being design document as such and code document. Neither of these documents describes programming of a specific routine or why it exists in a particular form. Instead, they define general requirements to stimulate the existence of the routine.

Comparison Document

Comparison document is also a breed of design document. It deals with a single aspect of the system and proposes alternative solutions, e.g. code, design, etc. but it may also propose an alternative solution for system architecture. Comparison document describes the current situation and proposes one or multiple alternative solutions, outlining both advantages and disadvantages of the proposed solutions. It is neutral in its nature and provides an insight into multiple solutions with an aim to find the best one. As a result, it involves lots of research to support its conclusions.