Bedienungsanleitung für das Arc42-Template
How to document Software Architectures
Dieses Dokument soll die Nutzung des arc42-Templates motivieren und vereinfachen.
Eine deutsche Version befindet sich in Bearbeitung, bis
dahin müssen Sie mit der englischen Vorlieb nehmen...
This document is available as pdf download (see Download-section).
1. Content and Scope
This document answers the following questions to both readers and writers of architecture documentation:
- For readers and writers (chapter 2):
- What are the ideas behind this kind of documentation?
- How is the documentation structured?
- How are the different sections of the documentation related to each other?
- How does structured documentation work to improve understanding of the architecture?
- How do diagrams and text work together to improve understanding?
- For writers:
- How is the document physically organized (that is, what is the architecture of the archi-tecture documentation?
- What building blocks (files, models) does it consist of (see chapter 3 for details)?
- How shall versions or releases of architecture documentation be built?
- How are the underlying UML models organized and maintained (see chapter 3.3)?
It provides an introduction to the software and system architecture documentation standard applied for (a revised and customized version of the arc42 architecture documentation template).
Acceptance criteria for architecture and architecture documentation, which shall be met by future re-leases of the architecture and the respective architecture and design documents, are described in an-other document (ArcDoc-Criteria)
What is „Architecture“
Architecture describes and prescribes the „solution“ to the requirements and, therefore, both describes and guides its implementation. Architecture is an abstraction of sourcecode artifacts and does therefore not describe or prescribe every implementation detail (but of the architecturaly relevant ones!).
The term software design can be used to describe implementation details: design = architecture-in-the-small. In our terminology, design is concerned with the internal structure of the lowest-level building blocks (see section 3.4 of this How-To and section 5, especially the elaboration of building blocks (XX reference)). The design of those lower-level building blocks is usually delegated to single developers, they design and develop the code-structure for these building blocks.
In context the term „architecture“ comprises software and system architecture. It consists of all structures, components, their interfaces and relationships, which together solve the requirements of the system .
The focus of architecture is mainly on achieving non-functional requirements, like maintainability, flexibility and understandability of the whole system, plus support for all functional requirements as well.