• Home
• How-To...
  • 2. Requirements
  • 3. Main Concepts
  • 4. Structure
  • 5. Meta-Model (Draft)
• Das Template
• Der Prozess
• Kurse
• Services
• Bibliothek
• Downloads
• Über...
• Sitemap

English

Dieser Inhalt ist unter einer Creative Commons Lizenz lizensiert.




Blog:
IT and more

3. Main Concepts

Use a Structure Template for Documentation

Architecture documentation relies on a standardized structure of its documentation:

• Chapters and sections of the documentation are predefined and fixed and in a specific order.
• Each section has a predefined purpose and scope of content.

This structure has been derived from the arc42 documentation template and is widely used in organizations from various industries.

Architectural Views to Separate Concerns

Any software architecture consists of several distinct structures, which have to be documented separately in so called “architecture views ”. Think of blueprints in normal building construction – there is one to show the outline of walls, doors and windows, another one to document heat- and water pipes and even another one for electric cables. Such a distinction shall be made in documenting and designing software systems. The following four views are highly recommended for software architecture (see chapter for samples):

• Context views: Show the system in the context of its neighbour systems. You can document the following context information:

  • Static (or building block) context, showing “logical” building blocks. Every neighbour sys-tem is represented as distinct building block. All channels leading in or out of the system are depicted.
  • Deployment context, showing the topmost deployment units or artifacts for the system.
  • Runtime context, showing the most important use-cases of the system in context of its neighbours.
  • Building Block views: Show the static structure of the system in terms of building blocks. They answer the question: “How is the system constructed from source code”? Every building block has a corresponding representation in source code. Examples: A building block can be a java package or a single java class, a set of (related) classes, a configuration file, a database script or a similar artifact.

• Runtime views: Show the behaviour of the system, namely the runtime-behaviour of its building blocks interacting with each other and the neighbour systems. They answer the question: “How does the system actually work, how are system functions beeing performed?” Runtime views of-ten have a strong correspondence to use-cases.

• Deployment views: Show the artifacts used to actually run the system togetgher with the re-quired hard- and software. They answer the question “How and where is my system installed and what are the infrastructure requirements?”

Top-Down Approach to Manage Complexity

In documentation of software systems one shall always begin with a top-level overview. Further details shall be added where necessary (top-down refinement).

This approach uses two kinds of abstraction-mechanisms:

• Blackboxes: These are described by their interfaces and functions only. Inner workings or inner structure is completely hidden – abstracted away. Blackboxes follow the information hiding prin-ciple, they hide their inner complexity. For further info on blackboxes see section 3.4.
• Whiteboxes: These are “opened-up” blackboxes, revealing inner structure and inner workings. Whiteboxes themselves consist of a number of (smaller) blackboxes.

Blackboxes can be refined by “opening” them, turning them into whiteboxes. At a certain level of detail, an architect will delegate the inner working of any blackbox to a developer, letting them design the imple-mentation of this specific blackbox.

In a similar fashion, the author of architecture documentation may refine and enhance the documentation for the function of a Blackbox by adding the relevant document for the underying Whiteboxes.

The architecture documentation shall follow this top-down approach: Beginning with a context view as defined in chapter 3 (called level 0, where the system itself is represented as a black-box) and drilling down, until an appropriate level of detail is reached. Usually 3-5 such levels are sufficient to describe a software architecture for most stakeholders.

Blackboxes do Describe Responsibility and Interfaces

Blackboxes are architecturally relevant building blocks of the system. They are documented with their purpose and responsibility and their interfaces:

• Purpose and responsibility briefly describes why this blackbox is relevant for the architecture, its main tasks or reason for its existance.
• According to the IPO-Model (German: EVA-Prinzip), a blackbox receives a certain input via its incoming interface, performs its processing and yields certain results via its outgoing interface. Those interfaces have to be described in order to characterize the blackbox. (See http://en.wikipedia.org/wiki/IPO_Model for details.)

Blackboxes provide the link between architecture, design and implementation of the system: On the low-est architectural level, the blackboxes either represent sourcecode themselves or shall be linked to a number of sourcecode artifacts.