I. Introduction

May the force of the proper word and diagram be with you.

Often software systems are in use for many years - and are constantly maintained and improved. Sometimes the life of software comes to a tragic end: missing maintainability and insufficient documentation are a risky game with uncertain outcome even for small changes. Marginal extension can only be done with massive efforts. The business value of the system fades away.

As a software architect, design your systems in a way that they are maintainable, flexible and understandable, thus thoroughly avoiding their „decay“. To achieve that you should not only fulfill the functional requirements but also concentrate on inner qualities of your system. One of your jobs is to adequately communicate its architecture in both written form and by word of mouth.

In this book we introduce you to arc42, a proven, practical standard for documenting and communicating software architecture – available free of charge! arc42 is based on years of experience and used successfully since 2005 in many companies and organizations in different application domains.

First of all arc42 is a template for architecture documentation.

It answers the following two questions in a pragmatic way, but can be tailored to your specific needs:

• What should we document/communicate about our architecture?
• How should we document/communicate?

Figure I.1 gives you the big picture: It shows a (slightly simplified) overview of the structure of arc42.

In case you are impatient and immediately want to see a worked-out example of arc42-documentation, you can jump to chapter II. It will show you how arc42-documentation feels like.

For the rest of you (or readers returning from chapter II) we will give you background information that will make your work with arc42 easier.

I.1 Basic Principles of arc42

Clear Structure

Compare arc42 to a cabinet¹ with drawers: the drawers are clearly marked with labels indicating the content of each drawer. arc42 contains 12 such drawers (a few more than you see in the picture above). The meaning of these arc42 drawers is easy to understand.

Therefore, arc42 offers you a simple and clear structure to document and communicate your (complex!) system. Starting with the goals and requirements for your system and its embedding
into its environment you can provide the important stakeholder of your system with adequate information about the architecture.

arc42 is optimized for understandability and adequacy. It naturally guides you to explain any kind of architecture information or decision in an understandable and reproducible context.

Individuals and organizations using arc42 especially like two things about it:

1. the understandability of the documentation resulting from its standardized structure (the drawers) and
2. the manageable effort to create such documentation. We call it “painless documentation”.

Independent of process models

You can work on the drawers of the arc42 cabinet in any order – whatever seems useful and adequate under your constraints. When you start a development from scratch you will probably start with requirements and goals; when you maintain or extend existing systems you may dive into the details of the building blocks immediately.

With arc42 you can start and stop working on your architecture documentation any time. The fixed structure of your cabinet enables you to continue any time. The only prerequisite is an agreed understanding among all team members about the meaning of the arc42-drawers.

Therefore arc42 is completely process agnostic.

Architecture documentation with little effort

The arc42 template is a framework for creativity and architecture work, a basis for discussion and feedback among your stakeholders, support for familiarization of rookies and much more.

arc42 is available under a liberal open source license. Therefore you can use it free of charge, even in commercial environment. Working with the arc42 template does not require additional effort for you and your team:

• You only describe things that your stakeholders really have to know.
• You explain facts and issues that are necessary to understand the system or individual design decisions.
• You only keep track of important architecture decision that you had to make anyhow.

arc42 helps you to find the most adequate drawer where facts, features and decisions are kept, so that all stakeholders can easily find them again.

Risk: Template Zombies²

We want to warn you about one risk when using arc42 template: users could interpret the template as a form and could be tempted to fill every field . We seriously dislike terms like “fill in” and “form”.

arc42 is intended to be a lightweight tool that can easily be adapted to your specific need. It is not nearly a “fill-in all fields” form.

Our deep aversion against forms and our fear of misuse of arc42 has motivated us to describe a series of basic tips (in chapter III). You should especially obey tip III-2 (economy) and tip III-3 (adequacy).

I.2 Why This Book

Organizations apply arc42 since 2005 to document software architectures. Since that time we (the authors) helped to introduce arc42, restructure existing documentations according to the clear structure of arc42 or develop and document new systems with arc42.

The downloadable template contains short hints and tips for each parts (the drawers). The overall structure is easy to understand; there are no hurdles to use the template.

Despite this simple and clear structure we have been confronted with a lot of practical every-day questions. We have answered those questions in this book – in the style of the missing manual³.

I.3 What This Book is NOT

In this book we focus on effective and efficient use of arc42 to document and communicate software architectures. We explicitly excluded a lot of other topics or disciplines.

This book is no introduction to:

• Software architecture and design. We assume that you have basic methodology know-how about software design and development. You are able to distinguish problem (requirements) from solutions (architecture, implementation). You know principles like separation of concern, information hiding, loose coupling, strong cohesion, simplicity, high consistency, and you separate domain and technical aspects in your implementation. You have learned about different views of your software architecture and cross-cutting concepts. We collected a few resources in the appendix.
• Your favorite technology: Sometimes people confuse specific technologies or frameworks with software architecture. We won’t intr#oduce any implementation technologies here, although you need to know about these when you design and implement systems.
• Architecture and Design Patterns: Productive software developers and architects immensely benefit by reusing well-proven solution approaches also known as patterns. You can find patterns (== proven solutions) for various problem domains, described in excellent printed and online sources. Fire up your favorite search engine…
• Modeling: You should be able to use models to abstract static and dynamic aspects of your system. We assume that you know how static models (building block, components, modules and their relationships) relate to the source code. And you also know basics about dynamic models (runtime models, process models)
• UML (Unified Modeling Language): We will explain in many of the chapters of this book how to use UML pragmatically and effectively. But we assume that you have basic knowledge about class diagrams, component diagrams, sequence and activity diagrams as well as deployment diagrams. More information can be found in [Booch+05] or [Pilone-05].
• Requirements Engineering and Business Analysis: software architects have to understand and potentially clarify requirements for a system. They may have to elicit, document and manage requirements – i.e. do work that ideally would have been done by requirements analysts. We assume that you know about functional requirements and quality requirements and are able to discuss them with your stakeholders. A good source for more information is [Robertson-12].

Although our tips mainly refer to effective usage of arc42, many of them will help you and your team to design and implement better systems.

I.4 Our Assumptions About You

When writing this book, we (the authors) had several (potentially silly) assumptions about you (the readers) in mind:

• First of all, you have loads of work to do. Therefore, you only want to read those parts of the book that you consider to be relevant for your work. For this purpose we have written the navigation guide in section I.5.
• You are an experienced software architect or developer. Therefore, you are aware of adequate documentation. You have practical experience with the development of architectures and software systems and therefore you are aware what adequate documentation should be.
• You are developing or maintaining mid-size to large, sometimes complex software systems.
• You work under timing constraints and only want to read the relevant parts of the book. Therefore, we offer you a navigation guide in section I.5.
• We assume that sometimes in your professional life you have suffered from missing or excessive documentation.
• You want to communicate or document information about the architecture, the structure and the implementation of your system.
• You do not want to waste time; you want to keep the effort on an adequate level: for some systems you will need detailed information; for other systems it is sufficient to concentrate on core topics.
• Maybe you are already aware of arc42 and want to know how to apply the template more easily, more effective or with more pragmatism.

I.5 Quick Navigation

Since you are very busy in your everyday life you might be interested in identifying the parts of this book that are most relevant for your concrete problems.

The following diagram gives an overview of this book. We have numbered the main chapters with roman numerals (I, II, III) so that you can easily distinguish book chapters from the section numbers in the arc42 template - for which we use the normal Arabic numerals 1 to 12.

Chapter II demonstrates the use of the arc42 template via a small open-source system. In this example you will see how a concrete architecture documentation could look like. For each of the 12 sections of the template you will also find a short motivation explaining why this section is in the template and what should be captured. You can read chapter II independently from the rest of the book.

Chapter III explains some basis rules of adequate architecture documentation, especially our pledge for “systematic thriftiness”.

Chapter IV contains tons of practical tips for each section of arc42 (i.e. for each drawer – to pick up the metaphor from the introduction). We briefly motivate each arc42 section. Therefore, there is deliberate (small) redundancy with Chapter II. Here we give answers to the questions that we received from our users and seminar participants. This is the most extensive part of the book.

Chapter V explains how to use arc42 in everyday life. You will find hints for creating new systems or amending existing systems, for agile projects and for very large projects with many subsystems.

Chapter VI introduces tools and tool categories you can use to bring arc42 to life.

Chapter VII answers frequently asked questions in various categories (sometimes referring to the tips of Chapter III to VI). We maintain and update this FAQ chapter online.

I.6 Conventions

Tip I-1: Our numbering scheme

In this book we offer more than 200 different tips around arc42. The numbering scheme aligns them with the corresponding book chapters: the roman prefixes (III, IV, V etc.) refers to the book chapter, the arabic number sequentially numbers tips within chapters.