Acknowledgments

Many people helped in the last few years with constructive comments and critique, advice and questions around arc42.

Ralf D. Müller is the good soul and tireless committer in the arc42 open-source universe: He answers support questions, maintains the tool-chain that generates arc42 from its AsciiDoc sources and keeps our Github-issues in check. Thank you so much!

We like to thank Martin Dungs, Uwe Friedrichsen, Phillip Ghadir, Mahbouba Gharbi, Franz Hofer, Prof. Arne Koschel, Jürgen Krey, Anton Kronseder, Prof. Bernd Müller, Alex Nachtigall, Axel Noellchen, Robert Reiner, Markus Schärtel, Roland Schimmack, Michael Simons, Boris Stumm, Daniel Takai, Eberhard Wolff, Oliver Wronka and Stefan Zörner for their support during preparation of this book.

Special thanx to Pedro Lafuente Blanco, Stefan Paal, Christopher Schmidt, Silvia Schreier, Per Starke and Oliver Tigges for their constructive and insightful reviews and suggestions.

innoQ supports arc42 by hosting the arc42 Confluence wiki and the arc42.org website. Christian Sarazin clears away all the technical debris. Thanx to my skillful, knowledgeable, competent and critical colleagues.

Cover design by Andreas Steinbrecher.

Parts of translation from the German original were supported by Sven Johann and Per Starke.

Gernot: thanks Uli, Lynn und Per: You are superb, the best family in the universe. My time with you is always too short.

Peter: Special thanks to my wife Monika. You not only survived yet another book project but enriched it by your helpful insights and comments from the non-IT world.

Status

Dear Readers,

the current version of this book is a pre-release: Only a few parts have been finished, many others (especially chapter IV) are still under heavy work.

We do our best to fill the missing gaps asap - and we will continue to publish early, publish often. Leanpub will notify you of updates.

Revisions

• V 0.2.0: March 26th 2016: first published version, containing I-III and V, skeletons of VI and VII.
• March 2016: new cover (thanx, Andreas), chapter 1, 2, 3
• January 2016: initial German version, start of translation on Leanpub.
• March 2016: Sven Johann joined the translation effort (thx!)
• April 2016: moved to Github with webhooks

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.

II. arc42 by Example

Chapter IV contains practical tips for each part of arc42.

The system documented here is a small open source system hosted on Github.

Tip II-1: Improve your arc42 skills by reading additional examples

Luckily there are additional examples for arc42 architecture documentation available from several different authors.

• There’s a Leanpub book, arc42 by Example, that contains several examples.
• Managing bike tours, by Michael Simons: Java based app, productive since several years.
• Chess engine, by Stefan Zörner (in German).
• Customer relationship management (CRM).
• VENOM, a large scale (artificial) e-commerce system. Contains fragments from various real systems, combined into a single legacy tragedy.

If you like YOUR example to be listed here, just drop us an email.

II.1. Introduction and Goals

HtmlSC supports authors creating digital formats by checking hyperlinks, images and similar resources.

1.1 Requirements Overview

The overall goal of HtmlSC is to create neat and clear reports, showing errors within HTML files. Below you find a sample report.

HtmlSanityCheck (HtmlSC) checks HTML for semantic errors, like broken links and missing images.

It has been created to support authors who create HTML as output format.

1. Authors write in formats like AsciiDoc, Markdown or other formats, which are transformed to HTML by the corresponding generators.
2. HtmlSC checks the generated HTML for broken links, missing images and other semantic issues.
3. HtmlSC creates a test report, similar to the well-known unit test report.

Basic Usage

1. A user configures the location (directory and filename) of an HTML file, and the corresponding images directory.
2. HtmlSC performs various checks on the HTML and
3. reports its results either on the console or as HTML report.

HtmlSC can run from the command line or as Gradle plugin.

Basic Requirements

Required Functions

HtmlSC shall provide the following checks in HTML files:

Reporting and Output Requirements

1.2 Quality Goals

1.3 Stakeholders

Remark: For our simple HtmlSC example we have an extremely limited number of stakeholders, in real-life you will most likely have many more stakeholders!

Additional information

• Section IV-1 contains additional tips regarding requirements in general.
• In reality, the quality requirements or pretty often neglected and/or remain implicit.
• A more complete overview of quality goals can be given in section-iv-10 on quality scenarios

II.2 Constraints

HtmlSC shall be:

• platform-independent and should run on the major operating systems (Windows(TM), Linux, and Mac-OS(TM))
• implemented in Java or Groovy
• integrated with the Gradle build tool
• runnable from the command line
• developed under a liberal open-source license

Additional information

• Section IV-2 contains additional tips regarding constraints.

II.3 Context

3.1 Business Context

3.2 Deployment Context

The following diagram shows the participating computers (nodes) with their technical connections plus the major artifacts of HtmlSC, the hsc-plugin-binary.

For details see the deployment-view.

Additional information

• Section IV-3 contains additional tips regarding the business and/or technical context.
• Details of the external interfaces shown in the context might be elaborated in the building block view. See section IV-5

II.4 Solution Strategy

1. Implement HtmlSC mostly in the Groovy programming language and partially in Java with minimal external dependencies.
2. We wrap this implementation into a Gradle plugin, so it can be used within automated builds. Details are given in the Gradle userguide.
3. Apply the template-method-pattern to enable:
   • multiple checking algorithms. See the concept for checking algorithms,
   • both HTML (file) and text (console) output. See the reporting-concept.

Additional information

• Section IV-4 contains additional tips regarding the solution strategy.
• Keep this part of your documentation very short, move extensive explanations, examples etc. to arc42-section 8 (concepts).

II.5 Building Block View

5.1 Whitebox HtmlSanityChecker

Rationale: We used functional decomposition to separate responsibilities:

• HSC Core shall encapsulate checking logic and HTML parsing/processing.
• HSC Gradle Plugin encapsulates all Gradle specific stuff
• Various kinds of UI (console, graphical) are handled by separate components.

Contained Blackboxes:

5.1.1 HSC Core (Blackbox)

Intent/Responsibility: HSC_Core contains the core functions to perform the various sanity checks. It parses the html file into a DOM-like in-memory representation, which is then used to perform the actual checks.

Interfaces:

Details are described in the HSC-Core Whitebox.

5.2 Building Blocks - Level 2

5.2.1 HSC-Core (Whitebox)

Rationale: This structures follows a strictly functional decomposition:

• parsing and handling HTML input,
• checking,
• creating suggestions and
• collecting checking results

Contained Blackboxes:

Source Files:

• org.aim42.htmlsanitycheck.AllChecksRunner
• org.aim42.htmlsanitycheck.HtmlSanityCheckGradlePlugin

5.2.1.1 Checker and <xyz>Checker Subclasses

The abstract Checker provides a uniform interface (public void check()) to different checking algorithms. It is based upon the concept of extensible checking algorithms.

5.3 Building Blocks - Level 3

5.3.1 ResultsCollector (Whitebox)

Rationale: This structures follows the hierarchy of checks, managing results for:

1. a number of pages/documents
2. a single page, each containing many
3. single checks within a page

Contained Blackboxes:

5.3.2 Interface Results

The Result interface is used by all clients (especially Reporter subclasses, graphical and command-line clients) to access checking results. It consists of three distinct methods for:

1. overall RunResults,
2. single-page results (PageResults) and
3. single-check results (SingleCheckResults).

See the interface definitions below - taken from the Groovy source code:

package org.aim42.htmlsanitycheck.collect

public interface RunResults {
    // returns results for all pages which have been checked
    public ArrayList<SinglePageResults> getResultsForAllPages()

    // how many pages were checked in this run?
    public int nrOfPagesChecked()

    // how many checks were performed in all?
    public int nrOfChecksPerformedOnAllPages()

    // how many findings (errors and issues) were found in all?
    public int nrOfFindingsOnAllPages()

    // how long took checking (in milliseconds)?
    public Long checkingTookHowManyMillis()
}

package org.aim42.htmlsanitycheck.collect

interface CheckResults {
    // description of what is checked
    // (e.g. "Missing Images Checker" or "Broken Cross-References Checker"
    public String description()

    // all findings (aka problems) found during this check
    public  ArrayList<Finding> getFindings()
}

5.3.3 Suggester (Whitebox)

For a give input (target), Suggester searches within a set of possible values (options) to find the n most similar values. For example:

• Target = “McDown”
• Options = {“McUp”, “McDon”, “Mickey”}
• The resulting suggestion would be “McDon”, because it has the greatest similarity to the target “McDown”.

Suggester is used in the following cases:

• Broken image links: Compares the name of the missing image with all available image file names to find the closest match.
• Missing cross references (broken internal links): Compares the broken link with all available link targets (anchors).

Additional information

• Section IV-4 contains additional tips regarding the building block view.

II.6 Runtime View

II.6.1 Execute all checks

A typical scenario within HtmlSC is the execution of all available checking algorithms on a set of HTML pages.

Precondition: HtmlSC has been called from a Gradle build and is properly configured.

Scenario:

1. User or build-server calls gradle htmlSanityCheck
2. Gradle executes build-target htmlSanityCheck via the HtmlSC plugin
3. The plugin executes method AllChecksRunner.performAllChecks with parameter Collection<File> filesToCheck andFile resultsDir
4. performAllChecks:
   1. creates PerRunResults instance
   2. creates a list of Checkerinstances, one for every available checking algorithm
5. iterate over all these Checkerinstances. Every instance:
   1. executes its own checks
   2. adds one instance of SingleCheckResult containing its own results.
6. reportCheckingResultsAsHTML creates the final report.

II.6.2 Report checking results

Reporting is done in the natural hierarchy of results (see the corresponding concept in section 8.2.1 for an example report).

1. per “run” (PerRunResults): date/time of this run, files checked, some configuration info, summary of results
2. per “page” (SinglePageResults):
3. create page result header with summary of page name and results
4. for each check performed on this page create a section with SingleCheckResults
5. per “single check on this page” report the results for this particular check

Additional information

• Section IV-6 contains additional tips regarding the runtime view.
• You often use runtime scenarios only to find or verify building blocks, not that much for documentation.

II.7 Deployment view

The three nodes (computers) shown in the diagram above are connected via Internet.

Prerequisites:

• HtmlSC developers need a Java development kit, Groovy, Gradle plus the JSoup HTML parser.
• HtmlSC users need a Java runtime (> 1.6) plus a build file named build.gradle. See below for a complete example.

buildscript {
    repositories {
        maven {
            url "https://plugins.gradle.org/m2/"
        }
        jcenter()
    }
    dependencies {
        classpath (group: 'gradle.plugin.org.aim42',
                name: 'htmlSanityCheck', version: '0.9.3')
        classpath (group: 'org.asciidoctor',
                    name: 'asciidoctor-gradle-plugin', version: '1.5.2')
    }
}

// location of AsciiDoc files
def asciidocSrcPath = "$projectDir/src/asciidoc"

// location of images used in AsciiDoc documentation
def srcImagesPath = "$asciidocSrcPath/images"

// path for asciidoc-gradle-convert
def htmlOutputPath = "$buildDir/asciidoc/html5"

// images used by generated html
def targetImagesPath =   htmlOutputPath + "/images"

// where HTMLSanityCheck checking results ares stored
def checkingResultsPath = "$buildDir/report/htmlchecks"

apply plugin: 'org.asciidoctor.convert'
asciidoctor {
    sourceDir = new File( asciidocSrcPath )
    options backends: ['html5'],
            doctype: 'book', icons: 'font',
            sectlink: true, sectanchors: true
    resources {
        from( srcImagesPath )
        into targetImagesPath
    }
}

apply plugin: 'org.aim42.htmlSanityCheck'
htmlSanityCheck {
    dependsOn asciidoctor // ensure asciidoctor->html runs first

    sourceDir = new File( htmlOutputPath )

    // files to check, in Set-notation
    sourceDocuments = [ "many-errors.html", "no-errors.html"]

    // where to put results of sanityChecks...
    checkingResultsDir = new File( checkingResultsPath )
}

Additional information

• Section IV-7 contains additional tips regarding the deployment view.
• Sometimes it’s useful to describe high-level deployment or infrastructure in the technical context in arc42 section 3.2, corresponding tips are given in this book

II.8 Technical and Crosscutting Concepts

8.1 Domain Model

8.2 Structure of HTML Links

Remark: For many web developers or HTML experts the following information on URI syntax might be completely evident. As we wrote this book also for different kind of people, we included this information anyhow.

HtmlSC performs various checks on HTML links (hyperlinks), which usually follow the URI syntax specified by RFC-2396. URIs are generally used to link to arbitrary resources (documents, files or parts within documents).

Their general structure is depicted in the following figure - you also find a unit test below.

@Test
public void testGenericURISyntax() {
    // based upon an example from the Oracle(tm) Java tutorial:
    // http://docs.oracle.com/javase/tutorial/networking/urls/urlInfo.html
    def aURL = new URL(
        "http://example.com:42/docs/tutorial/index.html?name=aim42#INTRO");
    aURL.with {
        assert getProtocol() == "http"
        assert getAuthority() == "example.com:42"
        assert getHost() == "example.com"
        assert getPort() == 42
        assert getPath() == "/docs/tutorial/index.html"
        assert getQuery() == "name=aim42"
        assert getRef() == "INTRO"
    }
}

8.3 Multiple Checking algorithms

HtmlSC uses the template-method-pattern to enable flexible checking algorithms:

“The Template Method defines a skeleton of an algorithm in an operation, and defers some steps to subclasses”.

We achieve that by defining the skeleton of the checking algorithm in one operation (performCheck), deferring the specific checking algorithm steps to subclasses. The invariant steps are implemented in the abstract base class, while the variant checking algorithms have to be provided by the subclasses.

/**
  * Prerequisite: pageToCheck has been successfully parsed,
  * prior to constructing this Checker instance.
**/
public CheckingResultsCollector performCheck() {
    // assert prerequisite
    assert pageToCheck != null
    initResults()
    return check() // subclass executes the actual checking algorithm
}

8.4 Reporting

HtmlSC supports the following output (== reporting) formats and destinations:

• formats (HTML and text) and
• destinations (file and console)

The reporting subsystem uses the template method pattern to allow different output formats (e.g. Console and HTML). The overall structure of reports is always the same.

The (generic and abstract) reporting is implemented in the abstract Reporter class as follows:

/**
 * main entry point for reporting - to be called when a report is requested
 * Uses template-method to delegate concrete implementations to subclasses
*/
    public void reportFindings() {
        initReport()            // (1)
        reportOverallSummary()  // (2)
        reportAllPages()        // (3)
        closeReport()           // (4)
    }

    private void reportAllPages() {
        pageResults.each { pageResult ->
            reportPageSummary( pageResult )                    // (5)
            pageResult.singleCheckResults.each { resultForOneCheck ->
               reportSingleCheckSummary( resultForOneCheck )  // (6)
               reportSingleCheckDetails( resultForOneCheck )  // (7)  
               reportPageFooter()                             
        }
    }

1. initialize the report, e.g. create and open the file, copy css-, javascript and image files.
2. create the overall summary, with the overall success percentage and a list of all checked pages with their success rate.
3. iterate over all pages
4. write report footer - in HTML report also create back-to-top-link
5. for a single page, report the number of checks and problems plus the success rate
6. for every singleCheck on that page, report a summary and
7. all detailed findings for a singleCheck.
8. for every checked page, create a footer, page break or similar to graphically distinguish pages between each other.

The sample report below illustrates this.

Additional information

• Section IV-8 contains additional tips regarding crosscutting concepts.

II.9 Design Decisions

9.1 Checking of external links postponed

In the current version of HtmlSC we won’t check external links. These checks have been postponed to later versions.

9.2 HTML Parsing with jsoup

To check HTML we parse it into an internal (DOM-like) representation. For this task we use Jsoup, an open-source parser without external dependencies.

To quote from the their website:

[quote] jsoup is a Java library for working with real-world HTML. It provides a very convenient API for extracting and manipulating data, using the best of DOM, CSS, and jQuery-like methods.

Goals of this decision: Check HTML programmatically by using an existing API that provides access and finder methods to the DOM-tree of the file(s) to be checked.

Decision Criteria:

• few dependencies, so the HtmlSC binary stays as small as possible.
• accessor and finder methods to find images, links and link-targets within the DOM tree.

Alternatives:

• HTTPUnit: a testing framework for web applications and -sites. Its main focus is web testing and it suffers from a large number of dependencies.
• jsoup: a plain HTML parser without any dependencies (!) and a rich API to access all HTML elements in DOM-like syntax.

Find details about usage of this parser in the HTML encapsulation.

9.3 String Similarity Checking using Jaro-Winkler-Distance

The small java string similarity library (by Ralph Allen Rice) contains implementations of several similarity-calculation algorithms. As it is not available as public binary, we use the sources instead, primarily: net.ricecode.similarity.JaroWinklerStrategy.

Additional information

• Section IV-9 contains additional tips regarding decisions.

II.10 Quality Scenarios

Remark: For our small example, such a quality tree is overly extensive… whereas in real-live systems we’ve seen quality trees with more than 100 scenarios.

10.1 Quality tree

10.2 Quality Scenarios

Additional information

• The most important quality goals (expressed as scenarios) have been summarized in the introductory section IV-1.2.
• Section IV-10 contains additional tips regarding quality scenarios.

II.11 Risks and technical debt

Remark: In our small example we don’t see any real risks for architecture and implementation. Therefore the risks shown below are a bit artificial…

11.1 Technical risks

11.2 Business or domain risks

Additional information

• Section IV-11 contains additional tips regarding risks.
• Help your management by informing them about technical risks - and options for their mitigation.

II.12 Glossary

In the case of our small example, the terms given here should be good friends to most developers. You find a more interesting version of the glossary in section II-8.1.

Additional information

• Section IV-12 contains additional tips regarding the glossary.
• Many terms in the glossary correspond to parts of the “Ubiquitous Language” from Eric Evans’ Domain Driven Design

III. Fundamentals of Effective Documentation

When designing and implementing complex systems, it is very helpful to distinguish between requirements (the problem) and the solution. When you improve your understanding of the problem, you can align the solution way better to these requirements.

Let’s begin by discussing the requirements to technical documentation and communication, independent of arc42. Afterwards we’ll present numerous pragmatic tips how you can create effective documentation simple, fast and with less effort than you ever imagined. Painless, nonviolent, without sophisticated tools or elaborate processes.

III.1 Documentation Requirements

Requirements for technical documentation will come from various stakeholders:

• Consumers (readers), who want to get their specific tasks done with help of the documentation. This group includes software developers, who want to read the documentation to implement new features in their system easily and quickly.
• Producers (authors), who produce and maintain documentation. They want to make changes in the system with minimal effort to update the doucemtation.

The following paragraphs summarize the seven commandments⁴ or rules for architecture documentation. The rest of the book focusses on how you can achieve these.

Rule 1: Helpful

Documentation has to be help all readers to perform their concrete tasks. It should ease or facilitate their work. Therefore the following relation must be true:

Even during system development architecture documentation should be helpful and not be regarded as an unnecessarily burdening extra effort.

Rule 2: Correct

Incorrect information in (technical) documentation can be as bad as software bugs. Even worse: Readers who find mistakes in one part of the documentation quickly loose their trust in the rest: The perceived value of the documentation vastly decreases.

Therefore, one important requirement for documentation is its correctness: Never (ever!) allow incorrect information in documentation. Correctness is the highest goal that you should never jeopardize!

Rule 3: Current

Correctness of documentation changes over time. What was correct yesterday could already be wrong today. You want your documentation to be current.

Rule 4: Easy to find

A specialization of “easy to use”: Documentation consumers shall be able to find information easily and quickly. Fixed structures (like arc42) and conventions help with that.

Rule 5: Easy to understand

Consumers (readers) have to understand documentation easily. Documentation has to fulfil their expectations in many dimensions: language, notation, form and tooling. Easier said than done - because sometimes the producers of documentation do not (yet) know all consumers that might need that documentation in the future.

Rule 6: Easy to change

Every change (enhancements, reconstructions, maintenance, and even bugfixes) can lead to necessary changes in the documentations. The easier it is for developers to adapt documentation, the higher the chances that the documentation really gets updated.

On the other hand, if changing the documentation is difficult and costly it is simple not done. Documentation then becomes outdated (loosing its correctness).

Many tips in this book address this requirement and show how to improve changeability of documentation.

Rule 7: Adequat

We don’t know how much documentation you really need for your system, how detailed you need it, and which notation you prefer. The stakeholders of your system may have special requirements and wishes concerning documentation based upon their specific tasks and experiences. arc42 suggests a pragmatic structure, but you have to determine the level of detail, adequate notations, and sufficient formalism for your system.

See also section VII.2 on the minimal amount of documentation.

III.2 Fundamental Tips for Documentation

Tip III-1: Appoint a Responsible Person (The Docu-Gardener)

In real life, gardeners have at least two different tasks: to plant (create new documentation)and to weed (remove outdated or unnecessary documentation). For (software architecture) documentation your gardener needs to:

1. care for the adequate form and content and
2. proactively search for unnecessary or outdated parts and remove them.

Please note: care does not mean your gardener shall create all content by her- or himself, but identify appropriate producers within the team or among associated stakeholders.

Tip III-2: Document economically (“Less is often more”)

When you create documentation, you implicitly create a mortgage for future generation: Whenever you modify your system, someone might need to maintain or adjust the corresponding documentation.

We really believe that documentation can be helpful and ease development work - but only in an extend and degree appropriate for the system and its stakeholders.

Our tips for appropriate (economical or thrifty) documentation:

• Less (shorter) documentation can be often read and digested in shorter time (but beware of overly cryptic brevity, so no Perl, APG or regular expressions).
• Less documentation implies fewer future changes or modifications.
• Explicitly decide what kind and amount of documentation is appropriate, and with what level of detail.
• Differentiate between short-lived, volatile documentation (i.e. flipcharts for your project work) and long-lived system documentation. See [tip V-6]{#tip-v-6}
• Dare to leave gaps: Deliberately leave certain parts of your (arc42) documentation empty. Especially within arc42-section 8 (crosscutting concepts) you can often remove numerous subsections that might not be relevant for your specific system.

Tip III-3: Clarify appropriateness and needs through early feedback

Type, amount and level of details of your documentation should be appropiate,
in relation to the system, the affected people, domain, risks, criticality, effort/cost and possibly even other factors. arc42 supports you with suggesting a documentation/communication structure, but does not suggests a certain form, notation, level of detail or target audience.

What appropriateness means in your specific case and for your system you have to find out for yourself, with help of your stakeholders:

At first, describe only a little part or aspect of your system - and get specific feedback for this documentation from involved stakeholders.

Ask stakeholders:

• What parts of this documentation is helpful?
• Which aspects need improvement? What kind of improvement?
• Which parts of the documentation should we enhance?
• Where can we shorten the documentation?
• Is the way of presenting, level of details and notation appropriate?
• Is the type of output (e.g.: pdf, html, docx, Wiki) acceptable?
• Do we have to document the parameters at the interface X in the architecture, or are the unit-tests enough?

For example, create diagrams in several iterations or refinements: Your first draft can be handwritten and really schematic. Through feedback you should quickly find out, if either your figure actually goes in the right direction (good) - or if your documentation does in no way fulfill the information demand of the stakeholders (bad). This way, you can sort out expectations through feedback. The more concrete you ask affected people for specific feedback and/or points of view, the more concrete their answers will turn out.

Avoid closed questions like “Is the documentation okay this way?” - because neither after a “yes” nor after a “no” you concretely know what to do!

Better ask open questions like “What do we have to change or enhance so that this documentation can support your work better?”

Tip III-4: Communicate top-down, work differently if necessary

Top-down means presenting circumstances starting from a high level of abstraction (few details), stepwise refining up to more details and concretisation. Such top-down communication generally facilitates understanding for all kinds of stakeholders.

On the other hand, a top-down communication structure should never enforce a specific developement method or a specific order of development activities.

Especially during developement it is often more effective to solve problems bottom-up. Communication and documentation of results should nevertheless be organized top-down.

arc42 supports this advice with it’s strict top-down scheme, see figure arc42 top-down.

1. arc42 sections 1 & 2 contain the introduction and goals, a brief summary of the systems’ requirements. This is the birds’ eye perspective on the system.
2. arc42 section 3 describes the context with the external interfaces. It’s an high-level overview and adds only little detail.
3. arc42 section 4, the solution strategy, gives a glimpse into the systems’ most influential decisions, concepts or approaches.
4. The building block view in section 5 is inherently organized top-down. It adds an arbitrary amount of detail to describe the how the source code of the system is structured.
5. The runtime view in arc42 section 6 shows typical or important scenarios that show how the building blocks interact at runtime.
6. Often the crosscutting concepts in arc42 section 8 contain detailed descriptions or specifications how certain recurring problems within the system are solved. Quite often this will be the most detailed part of architecture documentation.
7. The decisions in arc42 section 9 might be detailed, although several real-world documentations we encountered remained quite brief here, and instead focussed on the concepts in the preceeding section.

Tip III-5: Focus on Explanation and Rationale, Not Only Facts

Most facts about a software system can be found in its source code - but not their explanation, reasoning and rationale:

• Why is a specific white box structured as it is? Why does it consist of five blackboxes, not seven or eleven?
• Why was this (and not another) library/framework chosen to generate pdf documents?
• Why is one building block deployed on different hardware than all the others?

For arc42 documentation we propose to (briefly) explain at least the whitebox structures of the building block view. Furthermore you should elaborate surprising, special or risky decisions or concepts.

Tip III-6: Rate Requirements Higher than Principles

Specific requirements or goals shall always be more important than generic or global principles - as most of use are valued by reaching our goals, and only very few of for adhering to principles.

You should therefore treat arc42 or similar templates as pragmatic means, and definitely not as strict regulation.

Never treat arc42 as a form (like the yearly income-tax-form), but as a well-formed and prestructured cabinet with drawers (see figure “arc42-metaphor”).

Use these drawers as appropriate in your current and specific situation.

Stefan Zörner calls this approach (in his German book [Zörner-15]): „Use templates pragmatically“.

Tip III-7: Separate Volatile and Stable Documentation

We assume that you work in a project (rather short-lived) on a system (rather long-lived):

During development or maintenance of a system the development team needs efficient means for ad-hoc and often short-lived, temporary communication. For such project documentation, refrain from any formal or process requirements, if possible.

• Keep the entrance barrier for (written) communication as low as possible,
• Prefer low-tech tools over sophisticated electronic or online gadgets.

We call such documentation volatile, as teams need it only to support their development work - and many of these topics will not be relevant for the system on the long run.

See also tip V-6.

Eine verantwortliche Person (der Doku-Gärtner aus Tipp 1‑1) sollte diese Struktur (gemäß arc42) festlegen und gemeinsam mit dem Team angemessen mit Inhalt füllen.

Tip III-8: Don’t Repeat Yourself, If Possible

Vermeiden Sie unnötige Wiederholungen. Mehrfache Darstellung identischer Sachverhalte erzeugt überhöhten Pflegeaufwand bei Änderungen, und macht obendrein die Nutzung von Dokumentation schwieriger. Bei Redundanz ist die Chance recht groß, dass Sachverhalte an einer Stelle leicht anders beschrieben werden als an anderen Stellen. Das verwirrt Leser: Sind diese Unterschiede gewollt oder ein Versehen? Auf welche dieser Stellen kann ich mich verlassen, und auf welche eher nicht? Warum schränken wir dann bereits im Namen dieses Tipps auf „falls möglich“ ein, und fordern keine absolute Redundanzfreiheit? Der Grund liegt im Lesekomfort: An manchen Stellen möchten Sie Ihren Lesern Sachverhalte „als Ganzes“ vermitteln. Beispiel: Der arc42-Abschnitt 1 (Einführung und Ziele) erläutert die Anforderungen an das System. Hoffentlich haben Sie die Anforderungen in einem Requirements-Dokument, einem Lastenheft, einer Sammlung von User-Stories oder ähnlicher Dokumentation beschrieben. In der Architekturdokumentation möchten wir die wesentlichen Inhalte dieser Anforderungen komprimiert wiedergeben (Gewollte Redundanz!) – weil wir Lesern komfortabel diesen Extrakt der Anforderungen vorstellen möchten. Würden wir in diesem Abschnitt lediglich Hyperlinks auf andere Dokumente einfügen, wären wir einerseits redundanzfrei, andererseits zwängen wir die Leser dazu, die Informationen an völlig anderer Stelle nachzulesen… Also: Erlauben Sie Redundanz nur dort, wo sie den Lesekomfort oder das Verständnis erhöht.

Tip III-9: Document Unmistakably

Dokumentation sollte von allen Konsumenten gleichermaßen (eindeutig, non-ambiguous) verstanden werden. Nennen Sie gleiche Dinge überall gleich. Unterschiedliche Dinge brauchen unterschiedliche Namen. Eine Spezialisierung dieses Tipps lautet: „Erklären Sie Ihre Notation“: Sorgen Sie dafür, dass alle Beteiligten die verwendeten Notationen kennen. Bei Bedarf verwenden Sie Legenden oder verweisen (im Falle von Standardnotationen wie UML oder ER-Diagrammen) auf die gängige Literatur. Das hört sich vielleicht überflüssig an („ist doch jedem klar, was hier gemeint ist…“) – aber andere Personen könnten Ihre Symbole auf ganz unterschiedliche Arten interpretieren:

Ohne Erklärung der Symbole könnten Foo, Bar und bazz beispielsweise folgende (unterschiedliche) Bedeutung haben: ¥ Vom Hardware-Server Foo fließen bazz-Daten zum DB-Server Bar. ¥ Die fachliche Aktivität Foo sendet einen bazz-Event an den Prozess Bar. ¥ Das Skript Foo startet die Funktion bazz im Modul Bar… ¥ Die Funktion bazz übersetzt Foo in Bar

Sie sehen – ohne weitere Erklärung droht Missverständnis. Agieren Sie in dieser Hinsicht präventiv – und stellen Eindeutigkeit a priori sicher!

Tip III-10: Establish a Positive Documentation Culture

Ensure that documentation is a positive and friendly term within your team. Documentation shall support your stakeholders, never hinder them.

Persisting important architectural decisions, structures or concepts shall be regarded as something good, it’s positive for you and other stakeholders of your system.

For example, incorporate documentation in your Definition-of-Done (DoD), at least in case you’re developing in agile ways (what we really hope for you).

Tip III-11: Create Documentation From The Reader’s Point of View

Erstellen Sie Dokumentation für und aus der Sicht von deren Konsumenten ([Clements-11] nennt das „write documentation from the reader’s point of view“). Nehmen Sie die Stakeholder-Tabelle von arc42 (siehe arc42-Abschnitt 1.3) ernst: Darin sammeln Sie die konkreten Wünsche und Anforderungen Ihrer Stakeholder an das System und dessen Dokumentation!

IV. Effective use of arc42

In chapter II you got to know arc42 by means of a simple example. For all arc42 sections you learned why it exists and what you can communicate with it.

In this section you might encounter conflicting advice: We do that with intention:

Let’s look at one concrete example: In section IV-1 we recommend the use of activity diagrams, but also the use of numbered lists. What sounds like a contradiction is intended to demonstrate various alternatives. In some places we will offer explicit criteria for making a specific selection, in other places, the choice is just a matter of taste. In case of doubt, please use the incremental approach: get feedback on a (coarse or preliminary) version of a arc42-section and adjust detail or notation based on the feedback (see Tip III-2).

This Chapter Remains To Be Completed

IV.1 Tips for introduction and goals

IV.1.1 Requirements Overview

Tip IV-1: Compact summary of the functional requirements and driving forces.

This section is for many people the first thing they learn about the system. Here you should express the business or project goals clearly and concisely. Give a brief overview of what problem the systems solves. Note:

Note: Sometimes a requirements document relates to more than the one system that we focus on in our architecture documentation. If project scope and system scope are different, you focus in the particular document only the parts of the requirements that apply to this system.

• For systems with complex or extensive business requirements
• For systems without an existing (and reasonable) requirements documentation

Tip IV-2: Limit yourself to the essential tasks and use cases

List here the fundamental use cases, procedures, processes or user stories (however you call it in your organization). Limit yourself to a level of abstraction so that also outsiders are able to get an overview of the major tasks in a short period of time.

Tip IV-3: Highlight the business objectives of the system

You should ensure that the business objectives are explicitly known. Actually, this should already be in the project contract, or in the requirements specifications … Business objectives are often more global and on a higher level compared to the more detailed system requirements.

Tip IV-4: Create an overview by grouping or clustering requirements

In order to provide an overview of the functions of your system, describe in your architecture documentation only the importance of these groups without going into detailed individual requirements.

The figure below shows an example: some ellipses group (cluster) multiple requirements or use cases. Some of them can be found in the table

Tip IV-5: Make sure you can reference the requirements

In case you are referencing requirements in the architecture documentation, e.g. to justify a design decision, you need to make sure that these requirements can be identified by a short key or something similar

• Sometimes you can take those IDs from the requirements documentation.
• If your requirements are managed by a tool (e.g. an issue tracker), you can use those ID’s - with some tools you even have stable URLs.

Tip IV-6: Use activity diagrams to describe functional requirements

Tip IV-7: Use BPMN diagrams to describe functional requirements

In case your stakeholders perceive activity diagrams as too technical, you may use BPMN diagrams. The Business Process Model Notation explicitly addresses business stakeholders and can therefore be seen as an alternative to activity diagrams for describing business or technical processes.

Tip IV-8: Use a numbered list to describe functional requirements

In this context you could also use a numbered lists as simple and pragmatic way to describe activities, procedures or processes. The activity
mentioned earlier could then be exemplified as follows:

1. Authentication
2. Select a product
3. Check customer type
   1. Private customer, add the VAT (value-added tax)
   2. Business customer, ask for the VAT-ID
4. Create Invoice

In case you have to describe concurrent processes, activity diagrams see tip IV-6 are the better choice

Tip IV-9: Use (semi) formal text to describe functional requirements

We used PlantUml (http://plantuml.com/) to create the activity
mentioned earlier: This open source tool generated the diagram from the following textual description:

@startuml
start
:authenticate;

:select product;

if (private customer?) then (yes)
  :add\nVAT;
else (no)
  :request\nVAT_ID;
  endif

:create invoice;
stop

@enduml

Activities are between: and;, branches can be read as pseudo code and that way you combine the benefits of plain text with graphical representation.

IV.1.2 Quality Goals

You must know the relevant quality requirements of your stakeholders - preferably concrete and measurable. As an architect you need to know your success metrics …

Tip IV-11: Always work with explicit quality requirements

Requirement documents often focus on functional requirements, quality goals remain implicit (and therefore unclear, uncertain, interpretable …). However, you can captures the desired quality attributes relatively easy,

Tip IV-12: Explain quality requirements through scenarios

Scenarios explain in short sentences how the system should react in certain situations at certain events. There are several categories of these scenarios:

• Usage scenarios: how does the system react in certain types of use? In the example below: The execution time of an HTML-validation must not exceed 5 seconds.
• Change scenarios: how does the system behave when you change it or extend it? This allows you to identify how fast certain kinds of changes or extensions can be done or how much effort is probably needed.
• Failure or downtime scenarios: how does the system behave when a serious problem occurs, such as the failure of central hardware or software components.

Scenarios may relate to a variety of possible quality attributes, which are structured hierarchically by current quality models (e.g. ISO-25010). Some examples:

Change scenarios:

• A new algorithm for the routing of robots in a high-bay warehouse needs to be integrated. One developer can make this change within 4 hours including the modifications of the build and the unit and integration tests
• At the end of the year, the output format of the (annual) reports must be adjusted to fit new legal requirements. All required data are already in the database and the changes affect layout, formatting and aggregations. These changes can be fully implemented within at most 60 person-hours.

Usage scenarios

• The system selects the necessary data for the XY-process within 1 second (up to 100 concurrent users) or within 3 seconds (up to 1,000 concurrent users).
• After switching on, it takes at most 4 seconds until the navigation system accepts input from the GUI.

Tip IV-13: If you do not get quality requirements, make your assumptions explicit

We experience again and again that the development team receives no quality requirements from customers or key stakeholders. That leaves the quality goals implicit leading to a high risk of misunderstanding and dissatisfaction of all the people involved.

Our advice: based on your knowledge and experience, you can make assumptions about appropriate quality goals, the so-called educated guess.

Together with 2-3 team members, you could write down those assumptions as scenarios and discuss these educated guesses with your stakeholders. These assumptions are always better than having no explicit quality requirements!

Tip IV-14: Use checklists for quality requirements

With its hierarchical representation (see ISO 25010 figure below, the ISO standard 25010 provides a good checklist. Alternatively shows arc42-QA common quality characteristics.

• availability
• modifiability or maintainability
• performance
• security
• safety
• usability
• testability

Tip IV-15: Use examples to work out quality goals together with your stakeholders

The arc42-QA subproject contains more than 50 exemplary quality scenarios that you can use as a template for defining quality goals and requirements of your system.

Tip IV-16: Keep the introduction short! Show only the “hit list” of the quality requirements

Although you must meet all quality requirements that are demanded in the requirements and by the stakeholders, you should keep this section short. Show only a handful (“hit list”) of these requirements, possibly with only brief explanations and not only limited to a list of keywords. (all the other qualities can either be found in the specification or in the quality tree in arc42 section 10.)

Tip IV-17: Combine quality goals with the action points of the “solutions strategy” section

Sometimes you make decisions based on concrete and specific quality requirements. In such cases, it helps to document these quality goals and the resulting decisions in a consolidated table. We propose that you put this into the arc42 section 4 (solution strategy). In arc42-section 1.2 (quality goals), you only add a reference.

Tip IV-18: Show the detailed quality requirements in arc42 section 10

You should list a detailed overview of all quality requirements (quality tree and scenarios) in arc42 section 10 (quality tree). You can also represent there the relationship between the quality goals.

IV.1.3 Stakeholder

Content Explicit overview of all the stakeholders of the system, i.e., all people, roles or organizations who

• should know the architecture or
• must be convinced of the architecture,
• work with architecture or code (e.g., use interfaces),
• need the documentation of the architecture for their own work
• make decisions about the system and its development

Motivation

You should know the people who are participating the project or are concerned by it, otherwise you will experience surprises later in the development process. These stakeholders determine among other things the scope and level of detail of your work and results.

Tip IV-19: Search broadly for stakeholders

In order to give you some ideas, we came up with a frightening long list of possible stakeholders studying [Clements-11] as well as from looking at the template arc42. All these people or roles may have an interest in the architecture or its documentation …

Analyst, Business Analyst, (other) architects, auditor, supervisory board, project sponsor, public authority, council, build manager, business manager, database administrator, end users, enterprise architect, developer, external service providers, external partners, department, technical administrator, hardware engineer, hotline / support, infrastructure planners, integrator, IT strategy, lawyer, configuration manager, control panel, customer, steering committee, management, neighboring systems, network administrator, operator, product managers, product owners, project managers, QA department, release manager, rollout manager, Scrum Master, security officers, system integrator, tester, UX designers, related projects, maintenance team, designers, suppliers

Tip IV-20: Describe the expectations of the architecture and documentation stakeholders

Clarify the expectations of the stakeholders regarding the architecture and its documentation. Ask for expected shape, content and necessary detailing. Asking the stakeholders for their expectations can result in a lot of beenfits, even if it does not necessarily sound like architectural work:

• You respond to the specific needs of the stakeholders and thus achieve greater satisfaction among your target audience
• You avoid unnessessary work, because you focus on the content / topics that really matter to your stakeholders. You avoid to document things which might become important

Tip IV-21: Maintain a stakeholder table

You should explicitly represent the expectations of these stakeholders (see above) with respect to the architecture and its documentation in the form of a table.

You can find a minimal version in table below, which only outlines the expectations or required artifacts.

The table below shows a more detailed version including the relevance for approval and contact information. Please pay attention to any changes in the project teams and add next to the concrete persons, if necessary, also their replacement and work areas / departments / organization respectively.

Tip IV-22: Do not use the stakeholder table if your management already maintains a consistent stakeholder overview

In case your management (e.g. project management or product owner) takes the overview of stakeholders seriously and therefore maintains a stakeholder table, you should only cross-reference it in the architecture documentation.

But be careful: in our experience, project managers focus rather on organizational information about stakeholders (e.g., contact details and contact persons). In arc42 we need information about the specific expectations of the stakeholders with regards to the architecture and its documentation. We therefore propose that an architect should maintain the stakeholder table himself …

Tip IV-23: Classify your stakeholders by interest and influence

Especially while working under time pressure, you can only take care of a few stakeholders. In such cases, you could use a visual classification by interest and influence instead of a stakeholder table. Such a classification can be done very informally by gathering the team around a flipchart and put the outcome into the documentation as needed.

• High impact, great interest: you should involve these people intensively and/or take care of them. Do everything to satisfy this category of stakeholders in all respects. Communication pro-actively with them.
• High impact, no strong interest: invest just as much effort as needed to satisfy these stakeholders
• Little impact, strong interest: these stakeholders can be very helpful for the work on the system: involve them actively and keep them appropriately informed. They can particularly provide feedback on all types of technical or domain details.
• Little effect, little interest: here you could minimize your effort and only provide the information these stakeholders would consume when necessary

Ideally, you have a stakeholder table plus such a classification.

Note: some stakeholders might assess their own influence / power higher than it reflects your classification. Publishing this matrix could therefore lead to some of your stakeholders become quite frustrated.

IV.2 Tips for constraints

Content Restrictions, handycaps and company guidelines, which limit your freedom regarding design, implementation or development process. These contraints apply sometimes organization- or company-wide across the boundaries of individual systems.

Motivation

Tip IV-24: Look at the contraints of other systems within the organization

If you don’t know any contraints of your system, start looking on other systems within the organization.

Tip IV-25: Clarify the consequences of constraints

You should clarify the consequences of boundary conditions, e.g. resulting (additional) costs or effort. If constraints bring unreasonable consequences (e.g., can only be satisfied with excessively high costs), you should negotiate about them with the relevant stakeholders.

Tip IV-26: Describe organizational constraints

Organizational constraints like time and budget are for good reason unpopular with development teams, because they limit the freedom of design or implementation decisions very strongly. Therefore disclose these types of constraints.

Sometimes such constraints relate to development processes, third party contracting or legal concerns. Discuss them with your management.

Tip IV-27: Describe design and development constraints

In addition to the organisational constraints, technical contraints will probably apply as well to the design and development of your system. That can be guidelines from the managements or the organisation itself regarding hardware, operations, technology selection, use of products, frameworks or reference architectures. Disclose such constraints so that the development team can adjust to them in time.

Tip IV-28: Differentiate different categories of constraints

If necessary, differentiate between technical, organizational and political constraints or overlapping conventions (e.g., programming guidelines, documentation-, naming- or organisational conventions).

IV.3 Tips for the context view

The next few tips hold for both kinds of context. You find specific tips in section IV.3.1 (business context) and section IV.3.2 (technical context).

Tip IV-29: Explicitly demarcate your system from its environment

You should demarcate your system from the other IT systems in order to show how it fits into the existing IT environment, which external interfaces are offered or consumed and what users or roles are using the system.

That way you show the scope of your system: what are the responsibilities your system takes and what are the responsibilities of the other systems. The following diagram shows the context of a webshop which delegates the payment handling to an external provider (and this way removed from the scope of the webshop).

Tip IV-30: Show the context graphically

In the graphic context boundary, you should show the whole system as a black box, e.g., as a single component. Below are some examples of context diagrams. You have a variety of graphical options:

• Our favorite: UML component or package diagrams
• UML use case diagrams
• “Boxes and lines”

In any case, you should place your system in the middle and the other systems, roles, users, etc., around it.

Tip IV-31: Combine the context diagram with a table

You should always supplement the context diagram with a table. This way you can reduce the amount of labels in the diagram and easily add explanations, rationale or cross-references. The comprehensive context diagram above requires such a tabular explanation.

We only show excerpts of the corresponding table, but you should consider some characteristics of this typical “graphics/table” pair:

• You should use short identifiers within the diagram in terms of abstractions or generic terms. We use “Services” or “Market Data” in the example, which are then described in more detail in the table
• Reference within the table to more detailed explanations, e.g. if you are using terms from your domain language, you don’t need to explain them in the context, but refer to the relevant chapter (probably 8.1, domain modell).

Tip IV-32: Explicitly indicate risks in the context

You could use flashy colors or symbols to indicate risks. The diagram shows that the webshop uses a payment provider to process payments. Obviously, this is a very important service: the availability of the webshop may depend on the availability of the payment service.

You should highlight those risks in the diagram and explain them in the accompanying text. Ideally, you refer to the risk list of your project, or rather arc42 section 11.

Further examples of risks that you should point out clearly within the context:

• Availability risk: if external systems are down: an external system heavily influences the availability of your system.
• Cost risk: the usage of an external system is expensive, individual calls or other types of use cost money. Examples are credit card checks or payment/booking services.
• Security risks: you receive/send sensible data from/to external systems. That could make these interfaces particularly interesting for a potential attacker.
• Volatility (high probability of change) of external systems: Interfaces of external systems are changed often (they are “work in progress”). The syntax and semantics of the transmitted data could be changed on short notice, which means that you either have effort adapting to these changes or you need to develop a flexible consumer for these interfaces.
• Complexity risks: using this interface is exceptionally complex or difficult, because it might have complex data structures, uses esoteric frameworks, complicated handshakes or an arbitrary mixture of those.

Tip IV-33: The context should give an overview and should not contain any details

Show Details, e.g., from external interfaces or external systems, in the block view or external interface documents.

The diagram above contains too many details of the interfaces - you could replace the seven individual interfaces to the billing component by a single “Billing” interface and show the details later in the block view.

Too many details make communication and feedback about the context boundary complicated. However, you should here at least mention domain-specific inputs/outputs and protocols.

Tip IV-34: Simplify the context boundary through categorization

Keep the context boundary simple: summarize external interfaces, systems or user roles that have strong similarities. Show explicitly that they are categories or summaries.

In diagram above, the system “Foo” sends reports to users. In the refinement of level 1 on the right you can see two different types of reports for two different groups of users. This type of refinement is desirable and consistent. The context boundary marked reports accordingly as a category. You can find such categories for many criteria (see tip below).

Tip IV-35: If many external systems are involved, merge them by explicit criteria

If your system interacts with many external systems, you can combine several of these external systems by explicit criteria. You should explicitly state these criteria. Such criteria may include:

• Systems with whom we share common or similar data
• Systems with whom we communicate within the same use case or at the same time
• Systems with whom we communicate using identical or similar technologies (e.g. categorized by ftp- and WebService)
• Systems that belong to the same or similar organization, such as: all systems of garages, insurances, glass manufacturing and tax advisors
• Systems that have similar domain or technical tasks to solve (all systems printing documents, dealing with chip cards, etc.)

The example below marks the “Logistics” external system on the left as << category >>. On the right side, the detailed version shows three specific instances of the category << logistics >>.

Tip IV-36: Summarize “many external systems” with ports

If your system interacts with many external systems, you could use ports at the external interface of your system instead of displaying all external systems as separate icons. See below.

Das sieht auf den ersten Blick ungewöhnlich aus, kann aber Aufwand sparen. Vergleichen Sie die Diagramme aus Bild 7 und Bild 12 – es handelt sich um dasselbe System. This looks at first glance unusual, but can save effort. Compare the graphs of Figure 7 and Figure 12 - is the same system.

Tip IV-37: Show all (all!) external interfaces

We believe that aiming for completeness is usually a bad goal - with (at least) one exception: you should put all, really all, external systems surrounding your system explicitly into the context boundary. In order to save expenses, you could create categories, groups or clusters of external systems (see tip 4 34 and 4 Tip 35)

Tip IV-38: If you offer external interfaces to other systems, create discrete interface documents

The development teams building these external interfaces like compact and appropriate documentation about them. Therefore explain the usage (!) of the interfaces and not so much the fundamental concepts or justifications.

You can document REST API’s rudimentarily with tools like swagger (http://swagger.io/) or Apiary (https://apiary.io/)[^no_hypermedia_support]. Unit tests are a good choice to describe other types of external interfaces.

Tip IV-39: Differentiate domain and technical context

Especially with information systems, you can often ignore technical details of the infrastructure within the context boundary and focus on the domain related parts.

However, if hardware or technology plays an important role for your system, you need both, a domain as well as a technical context. See section 4.3.2 (Technical context).

In the figure after next below you can find a simplified example from the embedded world: the left side shows the domain context, the right side the technical context.

The figure below shows a small example of a (web-based) information system with domain and technical context.

You recognize protocols such as HTTPS or SSH within the technical context, which are intentionally not mentioned in the domain context.

Further, the (from a domain point of view external) component “Reporting” is deployed in the same technical infrastructure as the main system.

Wo ist der Hinweis zu (4 - In den Abschnitten IV.5 (Bausteinsicht) und IV.6 (Laufzeitsicht) gehen wir auf diesen Rat näher ein. Siehe Seite 30.)?

IV.3.1 Domain Context

Tip IV-40: Show rather data flows within the domain context

Apply this tip for information systems and not so much for real-time or hardware-oriented and strongly process-oriented systems. Since you are going to discuss the (domain) context boundary often with a variety of stakeholders, you cannot assume that detailed UML or modeling skills are known.

Intuitively, many people understand an arrow between software systems as data flow. (Directed) UML relationships like dependency, association, etc. are rather confusing for these individuals. Therefore: within the context, show data flows by turning around the direction of the arrow for conventional UML method or service calls.

Note: this advice is controversial in some teams, because we so explicitely do not comply with the standard UML notation, and also doing that only in the context. However, we found that data flows are often easier to communicate with (non-technical) stakeholders.

For the formalists among you: use the normal, dotted UML dependency arrow and annotate it with the stereotype << flow >> to indicate it as data flow and not as a control flow.

For less puristic UML users: invent a new arrow (e.g., solid line with arrowhead) and declare it - as suggested above - in the legend as data flow. IT veterans recognize here the the good old context diagrams from the structured analysis.

Tip IV-41: Show external influences in the context

Your system can handle different types of dependencies to external systems, e.g.:

• data or information dependencies
• temporal dependencies
• local or spatial dependencies
• hardware dependencies
• dependencies on persons, organisations or roles
• transitive (indirect) dependencies

Often you will only show user roles and data/information dependencies in the domain context. However, sometimes other types of dependencies can also be important for your system. Such dependencies can be described in the diagram itself or in an additional explanation.

An example is shown in the next figure: users must register before using the system (step 1), the system orders the text messaging (step 2), which an external text message provider sends via the mobile network (step 3). The user enters the code (step 4), and in step 5, the system verifies the identity of a person against an external branch identity server, which, in turn, triggers a verification at a registry office (step 6).

Steps 3 and 6 are transitive (also called indirect) dependencies. The system depends on the registry office, even if it doesn’t use it’s interface directly. The system is maintained by administrators, who have only access via a hardware device (Hardware Access Control, HAC). The system and the HAC must be physically in the same room - a spatial dependency. Some of these dependencies have impact on the achievement of the quality requirements for your system - and therefore can be risks (see tip IV 32).

Tip IV-42: Read Douglas Adams

We are currently at number 42: if you like science fiction, and at the same time have a quirky sense of humor … then Douglas Adams’ book “The Hitchhiker’s Guide to the Galaxy” would be a reading recommendation. After all, the number from arc42 comes from there…

Tip IV-43: Show transitive dependencies in the context

Systems have sometimes indirect (transitive) dependencies that may be relevant for communication with some stakeholders. Include those dependencies in your context. An example is shown in the figure above: The dependencies 3 and 6 as well as the registry office in the upper left corner are indirect.

Caution: transitive dependencies in the context contradict the rule of economicalness (as you get additionel elements by showing transitive dependencies). Therefore you should only describe them if it is necessary for understanding the actual situation.

Tip IV-44: Pay attention to quality requirements for interfaces

Special quality requirements may apply to interfaces of your own system and maybe as well to your external systems, e.g. safety, throughput or availability requirements. These so-called “service levels” need to be treated with care, because they may have high implementation and operating expenses and -risks.

Consider also (tip IV 32) with respect to risks of external interfaces.

IV.3.2 Technical Context

Tip IV-45: Show the technical context

You should show hardware and infrastructure of your system, such as computers, processors, networks or buses. Especially for integrated hardware/software systems (embedded systems) you almost always need a technical context. The embedded systems context diagram above (right side) is such an example. However, it may also be important for information systems to show some aspects of hardware and infrastructure already in the context, e.g. for security issues (see the webshop example above).

Tip IV-46: Use the technical context to describe protocols or channels

As you have already seen in the webshop and embedded software examples above, you can explicitly label protocols (SSH, HTTPS, VPN) or channels (CAN bus) within the context.

Tip IV-47: Explain the relationship between a functional interface and its technical realization

(wie übersetzen wir fachlich und technisch am besten?))

In case your functional interfaces are realized in the technical infrastructure through different technical channels, protocols or interfaces, you should explicitely describe the functional-technical mapping.

A simple example of such a situation can be found graphically here (Link-TODO). The relationships (mapping) can be described easily with a table:

Tip IV-48: Show the technical context in the deployment view

You can move technology and infrastructure into the deployment view (arc42 chapter VII) if your focus is on functional topics and abandon the technical context (arc42 chapter III-2)

But if technology and infrastructure is important to you, then you should give this overview already in the technical context.

Tip IV-49: Show variants of the technical context

If your system is used in different working or application environments, you can represent this in the technical context boundary. In the following figure you can see a system in a test environemt (left side) and in a significantly more complex production environment (right side). Alternatively, you can show such variants in the deployment view in arc42 section VII.

[^no_hypermedia_support] Silvia Schreier noted correctly that these tools unfortunately ignore hypermedia.

IV.4 Tips for solution strategy

Tip IV-50: Explain the solution strategy as compact as possible (e.g. as list of keywords)

Explain your solution strategy in keywords, e.g. as a short list of relevant decisions or approaches. You explain the details as a concept in arc42 chapter VIII (cross-functional concepts).

You should emphasize on creating an overview, not so much on completeness or a long explanations.

Tip IV-51: Describe important solution approaches as a table

<t.b.d.>

Tip IV-52: Describe solution approaches in context of quality requirements

<t.b.d.>

Tip IV-53: Refer to concepts, views or code

(instead of repeating such details in the solution strategy)

<t.b.d.>

Tip IV-54: Let the solution strategy grow iteratively / incrementally

<t.b.d.>

Tip IV-55: Justify the solution strategy

<t.b.d.>

IV.5 Tips for building block view

Tip IV-56: Use a common format for sections of the building block view

<t.b.d.>

Tip IV-57: Organize the building block view hierarchically

<t.b.d.>

Tip IV-58: Always describe level-1 of the building block view (“Level-1 is your friend”)

<t.b.d.>

Tip IV-59: Describe the responsibility or purpose of every (important) building block

<t.b.d.>

Tip IV-60: Hide the inner workings of blackboxes

<t.b.d.>

Tip IV-61: Document blackboxes as table using the minimal blackbox template

<t.b.d.>

Tip IV-62: Document blackboxes with the extensive blackbox template

<t.b.d.>

Tip IV-63: Document blackboxes as structured text

<t.b.d.>

Tip IV-64: Justify every whitebox (blackbox decomposition)

<t.b.d.>

Tip IV-65: Document whiteboxes with the minimal whitebox template

<t.b.d.>

Tip IV-66: Document whiteboxes with the extensive blackbox template

<t.b.d.>

Tip IV-67: Use runtime views to explain or specify whiteboxes

<t.b.d.>

Tip IV-68: Use inheritance to describe similar behavior of multiple building blocks

<t.b.d.>

Tip IV-69: Use crosscutting concepts to describe or specify of multiple building blocks

<t.b.d.>

Tip IV-70: Document multiple levels of the building block view

<t.b.d.>

Tip IV-71: Keep your external interfaces in context and building block view consistent

<t.b.d.>

Tip IV-72: Explain the mapping of source code to building blocks

<t.b.d.>

Tip IV-73: Describe where to find the source code of building blocks

<t.b.d.>

Tip IV-74: Organize the mapping of source code to building blocks according to directory structure

<t.b.d.>

Tip IV-75: Organize the mapping of source code to building blocks according to the modularization of the programming language(s)

<t.b.d.>

Tip IV-76: Ensure that every piece of source code has its proper place within the building block view

<t.b.d.>

Tip IV-77: In exceptional cases, include thirt-party software (libraries, frameworks, middleware etc) in the building block view

<t.b.d.>

Tip IV-78: Frugally document internal interfaces

As external interfaces are often more important or critical than

<t.b.d.>

Tip IV-79: Document / specify interfaces with unit-tests

We hope that you would create such unit tests anyway… so re-use them as part of your documentation.

<t.b.d.>

Tip IV-80: Document / specify interfaces with runtime scenarios

see runtime-view

<t.b.d.>

Tip IV-81: Use building block view level-1 for “further” information

e.g. management information, completion status, technologies used, release/deployment information

<t.b.d.>

Tip IV-82: Refine several building blocks at once, if that’s adequate

<t.b.d.>

Tip IV-83: If you refine several building blocks at once, ensure uniqe mapping

Every blackbox in the refined whitebox shall belong to exactly ONE blackbox on the previous level.

<t.b.d.>

Tip IV-84: Refine only a few building blocks

Economicalness.

<t.b.d.>

Tip IV-85: Document concepts instead of building blocks

Might save some effort.

IV.6 Tips for the runtime view

<t.b.d.>

Tip IV-87: Limit the runtime view to very few scenarios

<t.b.d.>

Tip IV-88: Explain schematic (generic) processes in the runtime view

<t.b.d.>

Tip IV-89: Explain concrete (specific)

scenarios in the runtime view

<t.b.d.>

Tip IV-90: Use runtime scenarios primarily to detect or identify building blocks - rarely for documentation

<t.b.d.>

Tip IV-91: Use sequence diagrams to describe or specify runtime scenarios

<t.b.d.>

Tip IV-92: Document or specify parial scenarios

<t.b.d.>

Tip IV-93: Use plain activity diagrams to describe or specify runtime scenarios

<t.b.d.>

Tip IV-94: Use activity diagrams with partitions to describe or specify runtime scenarios

<t.b.d.>

Tip IV-95: Use text to describe runtime scenarios

<t.b.d.>

Tip IV-96: Mix large and small building blocks within single runtime scenarios

<t.b.d.>

IV.7 Tips for deployment view

Tip IV-97: Document or specify the technical (hardware) infrastructure

<t.b.d.>

Tip IV-98: Document and explain the infrastructure decisions

<t.b.d.>

Tip IV-99: Document or specify the various (technical) runtime or staging environments

<t.b.d.>

Tip IV-100: Show the deployment view as hierarchy

<t.b.d.>

Tip IV-101: Document or specify the mapping of building blocks to hardware

<t.b.d.>

Tip IV-102: Use UML deployment diagrams for software-hardware-mapping

<t.b.d.>

Tip IV-103: Use building blocks instead of artifacts in deployment diagrams

<t.b.d.>

Tip IV-104: Use artifacts instead of building blocks in deployment diagrams

<t.b.d.>

Tip IV-105: Use tables to document or specify software-hardware mapping

<t.b.d.>

Tip IV-106: Explain intention or relevance of infrastructure nodes

<t.b.d.>

Tip IV-107: Document or specify everything which might be neccessary for operating the system

<t.b.d.>

Tip IV-108: Leave hardware decisions to infrastructure experts

<t.b.d.>

IV.8 Tips for crosscutting concepts

Tip IV-109: Restrict documentation of concepts to the most important topics

<t.b.d.>

Tip IV-110: In concepts, explain “how it should be done”

<t.b.d.>

Tip IV-111: Keep foundations of background information to a bare minmum

<t.b.d.>

Tip IV-112: Document or specify domain or business models

<t.b.d.>

Tip IV-113: Combine domain models with the glossary

<t.b.d.>

Tip IV-114: Document or specify the domain model

<t.b.d.>

Tip IV-115: Create at least a domain data model

Yes - we know that DDD is way more than just a data model - but if you don’t get at least your data right, your system is likely to fail…

<t.b.d.>

Tip IV-116: Document concepts by showing source code

<t.b.d.>

Tip IV-117: Document crosscutting concepts with the 4-quadrant-model

<t.b.d.>

Tip IV-118: Document decisions instead of concepts

<t.b.d.>

Tip IV-119: Use stereotypes to document which concepts are applied within which building blocks.

Show in building blocks which concepts are or have to be applied.

Tip IV-120: Use the arc42 topic proposals as checklist for crosscutting concepts

<t.b.d.>

IV.9 Tips for architecture decisions

Tip IV-121: Document the criteria for important decisions

<t.b.d.>

Tip IV-122: Explain reasons for important decisions

<t.b.d.>

Tip IV-123: Document or explain decisions as mindmap

<t.b.d.>

Tip IV-124: Document or explain decisions as table

<t.b.d.>

Tip IV-125: Document or explain decisions as “Architecture Decitions Record (ADR)”

<t.b.d.>

Tip IV-126: Document or explain discarded alternatives

<t.b.d.>

Tip IV-127: Document or explain decisions informally as blog

<t.b.d.>

IV.10 Tips for quality scenarios

<t.b.d.>

Tip IV-128: Keep the introduction (arc42 section 1) brief

Move details, especially of quality requirement, to this section 10.

<t.b.d.>

Tip IV-129: Document and explain the specific quality tree

<t.b.d.>

Tip IV-130: Document the quality tree as mindmap

<t.b.d.>

Tip IV-131: Use the quality tree as checklist

<t.b.d.>

Tip IV-132: Consider usage-scenarios in the quality tree

<t.b.d.>

Tip IV-133: Consider change-scenarios in the quality tree

<t.b.d.>

Tip IV-134: Consider stress- and error scenarios in the quality tree

<t.b.d.>

Tip IV-135: Use the quality tree for systematic architecture assessment/evaluation

<t.b.d.>

IV.11 Tips for risks and technical debt

Tip IV-136: Search for risks with different stakeholders

<t.b.d.>

Tip IV-137: Examine external interfaces for risks

<t.b.d.>

Tip IV-138: Identify risks by qualitative architecture evaluation

<t.b.d.>

Tip IV-139: Examine (development/deployment/etc) processes for risks

<t.b.d.>

IV.12 Tips for the glossary

Tip IV-140: Take the glossary seriously

(DE: Nehmen Sie das Glossar ernst) <t.b.d.>

Tip IV-141: Document the glossary as a table

<t.b.d.>

Tip IV-142: Keep the glossary brief and compact

<t.b.d.>

Tip IV-143: Restrict the glossary to relevant terms, avoid trivia

<t.b.d.>

Tip IV-144: Make the product owner be responsible for the glossary

<t.b.d.>

V. arc42 in Everyday Work

The main goal of arc42 is collecting useful and valuable documentation about an IT system, relevant for development and architecture. arc42 helps to achieve these goals, independent of your development process and the kind of your systems.

However, it’s not the goal to fill out arc42 completely. Remember the fundamental tips of chapter III: Document economically, oriented at concrete stakeholder requirements.

Secondly, work and document in the order appropriate for your specific system, usually not in the sequence of the arc42. In other words: Don’t let the arc42 template dictate a task order.

V.1 Good Start

Remember tip III-1, that proposes one responsible person (documentation gardener). This person can add documentation tasks to the backlog or delegate them to the team. The gardener shall not create all content by herself! In tip III-7 we formulated:

The responsible person (the documentation gardener from tip III-1) shall create … arc42 content together with the team.

Tip V-1: Explicitely clarify the target audience of your documentation

Develop an overview of all relevant stakeholders⁵ - at best in cooperation with your management. Put the result in arc42 section 1.2 (Stakeholder).

With this target audience clarify their concrete information requirements with respect to architecture and its documentation. See tip III-3 (Fast feedback).

Tip V-2: Use existing examples as jumpstart

You can find numerous public examples for arc42 documentation of different systems. Use an example to help your team get up to speed…

• Biking: Manage your favorite biking tracks, plus photos. Author: Michael Simons.
• Chess engine: Author: Stefan Zoerner.
• eCommerce (VENOM): Large scale eCommerce system for configuring and selling of complex systems. Author: Gernot Starke
• Customer-Relationship-Management (CRM): Managing customer relationsships in mass-market situations, like insurance cards or mobile phone tariffs. Mostly batch, complex interactions with external partners.

Tip V-3: Remove unneeded arc42-sections

Tailor the template to your specific needs: Adjust your documentation to stakeholder needs or requirements by removing parts or sections that nobody needs.

Tailoring absolutely requires a thorough understanding of documentation requirements - which you gain by applying tip V-1.

Please note: By tailoring you might alter the overall structure and/or section numbering of your arc42 documentation. This can make recognition of the structure a little more difficult for certain stakeholders, therefore apply tailoring with care.

Tip V-4: Augment arc42 by required sections or topics

In contrast to the preceeding tip V-3 you might need to augment the arc42 documentation of your system by some topics.

We have seen the following examples of adaptions in practice:

• Business or technical data models. In case you work primarily data oriented, or your domain contains complex data structures, a top-level section on those structures can signilize their importance.
• Screen or user interface layout: Create a top-level UI section if you base important architectural or technical decisions on your UI topics (like layout, typography or other visual topics). Might also be helpful if you need to intensively discuss layout or other UI topics with stakeholders.
• Required information for developers (developer guide): In case you have no separate documentation that describes important developer stuff (like environment, conventions, programming style and the like), an additional section in your arc42 documentation might help. We recommend to keep this info separate from the architecture documentation, though.

Tip V-5: Indicate currently unneeded arc42 sections

For systems demanding more formal documentation you should indicate those arc42 sections you don’t currently need or which are currently not required (as opposed to tip v-3). Add statements of the following kind to the corresponding arc42 sections:

• currently not needed
• will be documented for version/release x.y
• deliberately left out / omitted

Tip V-6: Prepare an arc42 repository for the team

Your development team shall focus on creating software, not on setting up documentation tools. You should prepare the required tools in advance: Prepare everything the team needs for lean, efficient and pragmatic documentation.

The concrete embodiment of this tip depends on your toolchain, see chapter VI.

The term repository means all media or tools your team needs to create or maintain documentation, the more centralized and homogeneous, the better.

For example, attend to the following:

• Create a wiki space for the project related (short-term) information. Part of this shall be structured analog to arc42. XXXX (link missing)
• Create a (prestructured) arc42 model within your favorite UML or modeling tool (in case your team sports such legendaries).
• Create a document for arc42, hopefully with something textbased like AsciiDoc or Markdown, or in the text processor of your choice.

Prefill such a repository with existing content, or content that stakeholders need to know.

In tip-iii-7 we proposed to separate system- and project documentation, like shown in the following diagram:

Tip V-7: Prepare a sandbox for documentation

Prepare a demo system, which the team can use to try out all documentation tools without risk.

Such a sandbox is especially important for (feature-rich) modeling tools: Their usage is often non-intuitive and non-trivial. Typical developers seldomly use such tools, therefore it is important to have small systems at hand to experiment with the tools.

Tip V-8: Document (and work) from different perspectives

Deliberately change perspectives from time to time to improve your understanding of relationships between different aspects. Reflect (some of) these perspectives in your documentation.

These perspectives can complement, augment and support each other, for example can a runtime scenario support understanding of a complex building block (or code) structure.

arc42 proposes a number of useful perspectives:

• Structural views (building blocks, runtime scenarios, infrastructure and deployment), arc42 sections 5, 6 and 7.
• Crosscutting or technical concepts, arc42 section 8.
• Black- and whitebox perspectives within the building block view, both part of arc42 section 5.
• Domain and technical perspective. The former helps to build the right system (do the right things), the latter to build it right (do things right).

Tip V-9: Documents belong into version control

When setting up tools for documentation, always keep version control in mind (exception: Wikis, which usually have their own version and/or change control). Documentation without both change history and reliable backup is not acceptable. We don’t care wether you use git, subversion, mercurial, TFS or other such tools - main point is you actively use one of those.

This tip might sound trivial - but we still (in the year 2016, deep in the 21st century!) find organizations that maintain Word(tm) documents on shared network drives and do versioning by appending consecutive numbers to filenames.

You should, of course, version binary documents (diagrams, images, office documents) too.

Please note: Maintaining models from UML tools within your VCS XXXX

Tip V-10: Conduct brief and thematically focussed documentation reviews

To ensure your documentation is adequate for your stakeholders you should ask for feedback as early as possible. Prerequisite is an overview of these stakeholders (see tip v-1).

Give selected, small parts of the documentation to selected persons for review. Ask specific questions instead of broad ones, similar to the following examples:

• Which additional information do you require in the description of interface X?
• Which parts of diagram Y are ok/correct/good, and which aren’t?
• Which changes/additions to the documentation do you propose?

Incorporate their feedback in a timely manner and repeat the review.

Tip V-11: Treat documentation tasks equal to developent tasks

Manage missing, insufficient or inappropriate parts of your documentation with the same processes and tools like any other development tasks, like features, tests or bugs.

For example, include reviewer feedback (see tip V-10) in your backlog or issue tracker. Even if the team cannot currently complete such tasks you keep an overview of open documentation issues.

Tip V-12: Document continously - parallel to development

In case you ever tried to move documentation to the end of a project, you know what happens in such cases: Documentation will never be created.

Therefore you should document continously - a little bit every day. In our experience even 15-20 minutes per day can lead to good results.

Both the fixed structure and the proactively prepared repository (see tip V-6) facilitate effective documentation even in small timeboxes.

Tip V-13: Always document in timeboxes

Timeboxes are a gread methodical tool to really focus on (and reach!) a specific goal. They help you concentrate on what’s currently important.

For every documentation task allocate a fixed time period (timebox) to that specific task: The more value that task, the more important the topic, the longer the timebox.

Such timeboxes should be at least 15 minutes long, but rarely longer than 4 hours. Only for huge documentation tasks your timeboxes should be even longer (see also tip v-15 on follow-up documentation).

At the beginning of every timebox (be it long or short!), invest a little time for planning and priorization. Answer the following questions for yourself:

• In the current situation, what’s the most important topic I need to document?
• Which approaches (textual description, bullet-list, table, diagrams etc) seem fit for this topic? What does arc42 propose? Do I see lean alternatives?
• For which stakeholders do I document? Who needs/requires/wants this documentation? (If the answer to this question is nobody, you better use this timebox to improve your source code or write some awesome integration tests.)

Tip V-14: Formulate like “The system {has|does|is|…}”

Sometimes you will write specifications or even requirements for a system or component to be built in the future.

An obvious option to formulate such topics is “the system { shall | should | will|…} “, to verbally indicate the futuristic character of your statements.

But: When the system will be build according to your specs or reqs, you will need to change such sentences, or rewrite them for your documentation. You can easily save this additional effort:

Therefore: Principally stick to indicative formulations (like has, does or is) instead of using conditional or future forms (like shall, should or will).

V.2 arc42 for Existing Systems

Software teams spend most of their time maintaining (modifying, correcting, improving, enhancing, tuning, patching, fixing…) existing systems - and not performing greenfield development (see section V-3) from scratch.

arc42 is well suited to support these maintenance tasks. You can use arc42 to effectively document your existing system a posteriori or in hindsight.

Your approach will depend on your current situation, wether you have:

• no documentation,
• too much documentation,
• outdated documentation,
• inhomogeneous documentation of varying quality,
• demand for specific topics/aspects

or any mix of these.

Tip V-15: Create hindsight documentation iteratively in short timeboxes

In case you currently have not usable documentation at all, you can create an acceptable overview with 3-5 persons within 2-4 hours (obviously depending on the size of your system and its criticality…)

Yes - you read correctly: We’re talking about a very small timebox here: Invest just a few hours instead of weeks:

Prepare a flip chart with the arc42 structure and provide sticky notes and pens. Choose a few (3-5) knowledgeable persons and proceed as follows:

• within 3-5 minutes (!) brainstorm answers to the following questions:
  • Which stakeholders are interested in documentation?
  • What is the minimal information those stakeholders need/require?
  • Which of these information do we already have?
• within 10-15 minutes work along the arc42 sections:
  • What are the most important information that we (developers, architects) need to keep?
  • Which of these information do we already have?
• Consolidate the results of these short brainstorming sessions: For every arc42 section, note:
  • the stakeholders interested in this section
  • where this specific information is already existing or
  • which stakeholders might contribute/create this information.

In the diagram below you find an example: Concerning the context, information already exists in the wiki, whereas building-block and deployment views are completely missing. Some concepts are documented in wiki and subversion…

From this comparison (“what you need” versus “what you have”) you can infer concrete documentation tasks, that participants can resolve in the remaining time of your documentation timebox. Focus on content, not on form. Refrain from using high-end tools but write on paper and draw sketches on paper.

The documentation gardener (see tip III-1) can selectively improve certain parts of this documentation: create beautiful UML diagrams, move content to your wiki or other documentation tool.

In the documentation timebox you should focus on the deltas between “need” and “have” and start addressing those!

Tip V-16: Create documentation before you continue development

As an alternative to the iterative documentation of tip V-15, you might work a priori instead: Document the following topics for your existing system before you continue development:

• Building block view level 1, source code structure on highest abstraction level (arc42 section 5.1)
• Solution strategy, essential technical, conceptual or structural decisions (arc42 section 4)
• Concept, crosscutting concerns, fundamental principles or implementation rules (arc42 section 8)
• Quality requirements (arc42 section 1.2) and decisions/solutions derived from those (solution strategy, concepts)
• Context with external interfaces (arc42 section 3)

Again - refine and detail iteratively, based upon stakeholder feedback.

Tip V-17: Document those parts you’re anyhow working on

To change small parts of a system in the course of bug fixing or enhancing, you often need to understand additional parts around the actual culprit. Developing this understanding usually requires more effort than performing the actual change.

Use this opportunity to enhance the documentation of the affected parts.

For example, if you modify a level-2 building block, document responsibility and interface of this component. Explain the context of this building block by means of embedding it into a level-1 whitebox - without striving for completeness. You might go even further, and show the external interfaces (or interface changes) required for this modification within the system context (arc42 section 3).

Dare to leave gaps in your documentation: Leave other parts on level-1 or even the context undocumented. You’ll be positively surprised how good your documentation will become ofter a few of such iterations.

Tip V-18: Make other documents unnecessary as quickly as possible

A real danger when creating hindsight (a posteriori) documentation is the (potentially incorrect) existing documentation.

Ensure existing documentation becomes completely superfluous:

• move valid information from existing documents into your arc42 repository
• tag this existing information with “needs care” or “to be overhauled” if this old information needs to be reworked
• if you cannot delete old documents, at least tag/mark them as “invalid” or “outdated”

Tip V-19: Remove superfluous or outdated documents

In some organizations we experienced documentation overflow: An abundance of documents and information, spread over dozens or hundrets of files on different network shares, content-management-systems or even modeling tools.

In such organizations it’s common that stakeholders create their own documentation and ignore other peoples’ documentation.

If you apply tip V-18 in the large, you should move the content of many of these existing documents or sources into your arc42 repository.

Initially, retrievability or findability is more important than consistency: Remove as many of the existing documents as possible and move documentation into the central arc42 repository.

You can improve the consistency of documentation iteratively over time.

Tip V-20: Explicitly reveal problems and risks

Collect technical and structural problems and risks in arc42 section 11 (risks and technical debt). Use those as basis for future improvements within the system and its documentation.

See the aim42 open source projects, which describes a systematic approach to software improvement, evolution and modernization.

V.3 arc42 for New Systems

When developing new systems from scratch you should create documentation to support the ongoing development.

Documentation shall enable and support communication between stakeholders, especially to avoid implicit assumptions. It shall facilitate stakeholders’ tasks.

Within the following tips we propose a number of alternative perspectives to successfully start software architecture documentation.

Depending on your situation you should invest in each of these perspectives. We don’t propose any specific order - use feedback and iteration to adjust form, detail and depth.

Tip V-21: Start with the (business) domain

Follow the domain driven design (DDD) and model domain entities and services. That’s an elegant bottom-up approach to create building blocks. In many domains, these entities and services are long-lasting and fundamental parts of any architecture. Therefore a model (for example as UML or entity-relationship model) of the domain should be part of your architecture documentation.

• Usually the domain models are part of the crosscutting concepts, located in arc42-section 8.1 (business models). That’s a good home for business service models too.
• Alternatively you include the (entity or data-oriented) part of your domain into a detailed layer of the building block view (e.g. arc42-section 5.2 or 5.3)

Tip V-22: Start with quality requirements

From the beginning of development you should care for the required quality of your system. This especially holds if these kinds of requirements are missing from your requirements documentation.

As soon as you have worked out some quality scenarios based upon major quality goals (see arc42 section 1.2 and section 10), you should collect appropriate solution approaches together with your team. Like explained in tip iv-51, arc42 section 4 (solution strategy) is an ideal place for quality goals plus corresponding architectural decisions or approaches.

XXX: example table of scenarios plus approaches

Tip V-23: Start with the context and external interfaces

We cannot repeat it often enough:

Start early in development by demarcating your system against its neighbours (the context, in arc42-section 3). Iteratively improve this early version of the context over time.

See also tips iv-29 up to tip iv-49.

Tip V-24: Start with the solution strategy

A brief brainstorming with essential stakeholders (especially the development team) will usually result in ideas and proposals how to tackle the problem at hand: What technologies or patterns to use and how to apply them.

Briefly sketch these ideas in arc42 section 4 (solution strategy). Keep this section short and compact. In case you need more extensive documentation, include it in the appropriate part of arc42 section 8 (crosscutting concepts).

You can document the solution strategy within hours (for small to medium systems) or a couple of days (for larger systems) - but you definitely need to have the appropriate stakeholders on board - who can really explain the nitty-gritty details of the solution approaches.

V.4 arc42 for Agile Projects

We already argumented in favor of lean, pragmatic, agile and economical (that is, appropriate) documentation.

If it is possible within your organization, try to strive for economicalness, frugality, brevity and a clear stakeholder focus for your documentation.

Refrain from producing waste that nobody will use in the future.

Tip V-25: Take documentation serious even in agile projects

Even in agile projects a certain amount of documentation will be useful or required. Even well functioning agile teams will encounter some change, even agile team players sometimes forget some details.

Good agile teams that are successful on the long run work very disciplined and properly. They value inner quality of their systems, both code and documentation are maintained appropriately.

You read about appropriateness in several occasions within this book, especially tip III-3 (appropriateness) and tip III-6 (requirements over principles).

Tip V-26: Make documentation part of the Definition-of-Done

The Definition-of-Done (DoD) is a team specific understanding of all expectations that software and accompanying artefacts must live up to in order to be done (meaning: releasable into production). DoD is a well established practice from agile methods, especially Scrum:

DoD consists of a list of tasks and artifacts that deliver value to the system, create appreciation from corresponding stakeholders.

You should convince your team to add appropriate parts of technical documentation to your DoD. Important stakeholders might support your argumentation by stating the value they gain from proper documentation.

Tip V-27: Apply an iterative and incremental approach to documentation

Document iteratively and incrementally: Start with very little content, focus on important topics, concepts, decisions, interfaces or building blocks. Add content (== increment) based upon feedback from stakeholders.

Rinse and repeat.

Such iterations assure that you document lean and economically, according to tip III-2 and tip III-3.

See also tip V-10 (review documentation), tip V-12 (document continously) and tip V-13 (document in timeboxes).

Tip V-28: Use walls instead of electronic tools

During the time a team works cooperatively on a system, it’s highly useful to continously keep imporant information (diagrams, structures, models, concepts or similar) in sight, so everybody can see and comment it.

Print out (or sketch by hand) the context diagram plus the topmost level(s) of the building block view. Pin them to a wall in your project room. If that’s forbidden, grab a cork- or notice board for these diagrams.

Group discussions are way easier with pens in front of a wall as within a complex UML tool. Periodically include changes from the wall into your (electronic) repository. Replace overly scribbled paper by new and adapted printouts. That requires only minimal effort from your side.

For parts or aspects that are currently under heavy diskussion, boards with moveable notes are ideally suited. We love stattys⁶ to symbolize building blocks and (erasable) pens for dependencies.

Tip V-29: Enable cooperative work, even for distributed teams

Paper and whiteboards are the simplest tools for cooperative creation of ideas - not that much for documentation.

These low ceremony tools help you with planning tasks and projects, but you should provide additional tools for your documentation.

Tools like Google-docs, Dropbox-paper or similar web based apps allow concurrent access and coordination of distributed work.

V.5 arc42 for Large Scale Systems

Very large systems are often maintained by many persons in parallel. Consistent and appropriately-economical documentation of such systems poses a number of organizational and technical challenges.

We summarized our most important suggestion (modularization) in the following tip V-30. Nevertheless there are additional tool requirements for large systems (see chapter VI)

Tip V-30: Modularize extensive documentation

Factor out (extract) documentation commonalities of the system and create separate documentation for relevant subsystems.

Link up these different parts of the documentation by hyperlinks, so that consumers can navigate freely between special and common parts.

A toolchain supporting modularization is an important prerequisite: it’s a nuisance with typical office products, but works quite smoothly with wikis (see section VI-4) or markup-languages (see section VI-3).

For a schematic example of modularized documentation see figure arc42-modularized: The overall systems is made up from three subsystems. The common architecture documentation contains the introduction and goals, strategic decisions, building blocks level 1 plus crosscutting concepts. All these informations are valid and useful for the other three (smaller) documents.

Each subsystems’ documentation contains only parts of the arc42 template, and each subsystem focusses on different aspects.

The common part of your architecture documentation will most often contain the global system goals and the overall business context. Eventually it will also contain the solution strategy plus some crosscutting concepts.

Tip V-31: Extract goals, context and concepts

As proposed in the preceeding tip V-30 you should factor out documentation commonalities of the system and create separate documentation for relevant subsystems.

A central document appoint (or documentation hub) for the overall system should at least contain the systems’ goals, its context with the external neighbours and some crosscutting concepts.

Extracting these commonalities saves effort for the subsystems’ documentation.

Tip V-32: Appoint a responsible person responsible for the overall documentation

In case you follow our advice to modularize documentation, you should appoint a responsible person for the extracted (factored-out) part of the documentation - similar to the documentation gardener we proposed in tip III-1.

Tip V-33: Unify the documentation toolchain

<t.b.d.>

Tip V-34: Leave documentation of IT-landscape to enterprise architects

<t.b.d.>

Tip V-35: Structure your overall documentation along organizational boundaries

<t.b.d.>

VI. Tools for arc42

VII. Frequently Asked Questions

Just in case your question(s) regarding arc42 and its usage in practical situations are still missing - please let us know: Either as an email to info@arc42.de or by opening an issue on our github project.

VII.A General questions

Question A-1: What does the 42 mean?

“42” is a quotation from the science-fiction novel Hitchhikers Guide to the Galaxy by the famous Douglas Adams.

In his book the number 42 is the “answer to the meaning of life, the universe, and everything” - calculated by a very big computer over a very very long time:

Software developers like to use 42 as magic number, that’s a number without any real significance, which you could replace by any other number. Of course the name arc42 wouldn’t sound half as cool if we had choosen another number.

Question A-2: What’s the license?

Creative-Commons Sharealike 4.0

Under this license, you’re free to:

• Share: copy and redistribute the material in any medium or format
• Adapt: remix, transform, and build upon the material for any purpose, even commercially.

We, the licensors, (Gernot Starke and Peter Hruschka, the creators of arc42) cannot (and surely will not) revoke these freedoms as long as you follow the license terms.

You must give appropriate credit, provide a link to the license, and indicate if changes to arc42 were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.

If you remix, transform, or build upon material from arc42, you must distribute your contributions under the same license as the original.

Question A-3: What’s the pricing model of arc42?

arc42 is completely free to use (and will remain so!), for arbitrary kinds of system, even in commercial context.

Question A-4: How widely is arc42 used?

In the D.A.CH. region (Germany, Austria, Switzerland), arc42 is used by many organizations and corporations in various industries. We don’t know any statistically relevant numbers, though…

In these countries, alternatives like Simon Browns’ SA4D/C4 model are not well-established.

In the international scene, we guess that arc42 is way behind SA4D/C4.

The template is available in English, German and Spanish. Further translations are most welcome (but will not be provided by the current maintainers of arc42).

Question A-5: What’s the target audience of architecture documentation?

Short answer

(Potentially) all stakeholders of a system, that require information about the architecture, e.g. the internal structure, crosscutting concepts or fundamental decisions.

Longer answer

Which persons or roles are interested in what parts of the architecture depends on the specific context. Some typical targets for such documentation:

• Software developers who actually implement within the system.
• Software developers of neighbour systems, who need to know about external interfaces and/or their technical details.
• Software architects who need to prepare, shepard or implement architectural decisions.
• Operators or administrators of software systems, who either need to configure the system for specific infrastructure needs, optimize it or perform administrative tasks requiring architectural understanding. This often includes security relevant tasks, like firewall or database settings.
• Technical managers who organize maintenance or evolution of the system.
• Auditors or reviewers, who valid, current and accurate architectural information to assess or evaluate the system.
• Testers and QA-engineers who need to plan, impelement or perform whitebox-, performance- or security testing.
• Consumers of services offered by the system, in case they need to understand additional details apart from the interface (blackbox) specification.

In our opinion, software architects should maintain an overview of current stakeholders together with their specific needs for architectural information.

Question A-6: What are possible alternatives to arc42?

• Simon Brown’s SA4D/C4 model. You find a brief introduction in one of his blog posts
• The View-Model of Paul Clements et. al from the Software Engineering Institute. From our point of view, their approach is very heavyweight and can become quite formal when applied to real-world projects.
• In case your organization has created its own “Software Architecture Documentation Template”: It should contain quality requirements, a scope/context section and information about building blocks and crosscutting concepts. If it does, you’re pretty close to arc42 anyway…

Question A-7: For what kinds of systems is arc42 applicable?

Short answer

Due to its flexibility concerning tools, processes and extend, arc42 is well-suited for all kinds of IT-systems (small to large, simple to complex, all kinds of implementation technologies).

Longer answer

For highly-critical systems, (e.g. safety-critical systems, where health or life are at stake), you need to seriously consider documentation requirements. In such cases, arc42 might not be the adequate approach (see question A-8).

We recommend to a-priori evaluate arc42, and enhance it according to your specific needs in such cases. Let domain experts or appropriate auditors review the resulting documentation structure.

For all other normal systems you can apply arc42: Depending on risk, complexity, scope or size you should assess both the arc42 structure and your toolchain for fitness regarding your specific purpose.

We successfully worked with dozens of clients in small, medium and large organizations on many different systems with arc42 - and it never let us down :-)

Question A-8: In which cases shall we NOT use arc42?

If you’re creating safety-critical systems, e.g. medical or avionics systems, where health or life are at stake, you will most likely encounter comprehensive and formal specification and documentation requirements, that arc42 will most likely not fulfill.

Many of the hints and tips we give for economical documentation might not be valid in such cases.

Question A-9: How can I contribute or report bugs in arc42?

• We maintain the template itself at Github. You can fork the repository and send us pull requests…
• You can open issues in this repo
• You can email us, or contact us over Twitter.

VII.B Questions on methodology

Question B-1: Which parts of arc42 are “essential”, which are “optional”?

Short answer

Please don’t fill in everything. Document only what your stakeholders need (you should ask them, one-by-one).

Longer answer

Everything you document will potentially require maintenance effort in the future. With every piece of documentation, you’re effectively piling up maintenance debt - and in parallel creating some information value…

Please only document things, facts and reasons that you or your stakeholders consider important enough to justify written documentation.

Question B-2: Does arc42 prescribe or enforce specific notations?

No, arc42 works completely (!!) independent of notation or syntax.

Question B-3: Shall I use UML for arc42 documentation?

You don’t need to - but:

UML notation is well-supported by various (free and commercial) tools, has a clear semantic and is pretty much standardized - therefore we (Peter + Gernot) like it.

On the other hand, UML does not guarantee any positive effects for your architecture or your team. Other notations might work as good (or bad) as UML.

You need to ensure that all stakeholders have a mutual understanding of your notation. That can become really difficult, if you draw only boxes and lines - as those have no semantic at all (at least without further explanation)

People tend to interpret such symbols in a way they like - most likely different than the original author intented…

See question D-4.

Question B-4: What is the minimal amount of an arc42 documentation?

Short answer

There is no general rule - as the minimal amount depends on the system, its stakeholders, criticality, complexity, size and/or risks.

Longer answer

We suggest to always explain, document or specify the following aspects:

• 3-5 central quality requirements, expressed in scenarios.
• Context view and external interfaces
• Brief explanation of your solution strategy, the most important decisions influencing the implementation or operation of the system.
• Building block view, level 1.
• Most important crosscutting concepts.

Question B-5: Where to document external interfaces?

Short answer

Both scope/context (arc42 section 3) and building block view (arc42 section 5) provide adequate room for external interfaces.

Longer answer

How and where you describe external interfaces depends on several factors:

• If your system provides external interfaces to external consumers and you and your team can decide about any details of these interfaces - then you have to care for their documentation.
• Do you need to provide external systems with information on how to use your interfaces? You could provide example code and other interface documentation, but need to make sure this information is easily accessible to the external stakeholders.
• Do you just provide data at your external interfaces, and no services? Then you might stick to just a documentation of data formats (and maybe semantics).
• In case you use interfaces provided by external systems, make sure their documentation is easily accessible by your development and maintenance teams. Include references in the arc42 context or building block view.

See also question B-6 (how to document interfaces)

Question B-6: How to document external interfaces?

Short answer

Document / specify interfaces by providing unit-tests. We hope that you would create such unit tests anyway, so you can re-use them as part of your interface documentation.

Longer answer

Describe syntax, semantic, protocoll/interaction of your interfaces, show sample interactions, provide sample data. Add some unit tests and/or other example code.

Question B-7: Where to put links to external systems (“neighbors”) documentation?

Use the context view to reference external systems’ documentation or to provide references to the parts of your arc42 documentation containing appropriate information.

If an external system/interface is especially important or risky for your architecture, it’s sometimes adequate to copy parts of this interface document into your own arc42…

Question B-8: What is a blackbox / the blackbox template?

A blackbox is a building block or component of the system which can be explained or defined in terms of its inputs and outputs, without knowledge of its internal workings.

You can easily document or specify a blackbox with a simple template. We propose a table for it, in the following form (required information in bold, the rest is optional):

Question B-9: What is a whitebox?

A whitebox contains multiple building blocks (blackboxes) with their relationships. It is a more detailed view of a blackbox of a higher abstraction level. You find an example in the diagram below:

This whitebox contains three blackboxes (A,B,C) and some relationships - a few of which are labelled.

Question B-10: What is the building block hierarchy?

The building block view explains your source code in a hierarchical way:

The topmost level (level 1) represents the white box description of the overall system, made up of black box descriptions of the system’s top level building blocks.

Level 2 zooms into the building blocks of Level 1 and is thus made up of the white box descriptions of all building blocks of Level 1 together with the black box descriptions of the building blocks of Level 2.

The following diagram shows a (rather generic) example - starting the hierarchical decomposition from the context view (called level-0 in arc42 terms)

Question B-11: How to document a whitebox with the whitebox template

The whitebox template is a structured means of specifying or describing whiteboxes. It contains the following elements (required information in bold, the rest is optional):

Question B-12: Where shall I describe important (blackbox) components?

The building block view should be a hierarchical explanation of your source code, of the static (code) structure of your system. It contains blackboxes of various level-of-detail.

It can be very understandable to make your important blackboxes part of your topmost refinement level, which we call level-1 in arc42.

If your important blackbox is something quite small which you don’t want to explicitly contain in level-1, then you could contain it in any refinement level - and mark it in its containing whitebox in color or by other visual means: Draw it larger than others, attach a graphical label/icon to it, give it a colored border - anything to let it stand out. Be pragmatic!

See also the questions in section C-5 (Building block view).

Question B-13: Can I use arc42 in agile projects, e.g. with Scrum?

Yes, of course. See also:

• section E (Agile), especially question E-1 (arc42 and agile methods).
• Question B-16 (economical documentation)

Question B-14: Can I update documentation incrementally? Or shall I document after the implementation is finished?

Short answer

Create and update documentation continuously - in sync with your sprints or iterations.

Longer answer

If you defer documentation to “later”, I am reasonably sure it might never be done. Don’t procrastinate - but make (brief, short, compact, economical) documentation a habit, like checking-in source code in version control or writing automated tests (you test, don’t you?).

In my opinion it’s way better to have short up-to-date and current documentation of only some aspects of the system, than to just have a plan to sometimes document the whole system…

Reserve a brief period of time every day (or at least every week) to catch up with your documentation tasks. Close your door, your email reader and your messenger apps, flip your phone to silent mode… and jot down some important, interesting, risky or otherwise valuable information about your current topics.

Question B-15: What kind of information shall I provide for which stakeholder?

See also question A-5 (target audience of architecture documentation).

Short answer

You need to inquire with your specific stakeholders, we can only give you rough approximations from our experience… that will most likely miss the goals of people involved in or with your system.

Show them examples what you could deliver with low effort. Incorporate their feedback. See #tip-iii-3 (appropriateness).

Longer answer

Read the short answer above! Ask your specific stakeholders, what artifacts or information they expect or require from the architecture documentation (or more general, the technical documentation).

Don’t ask what they require from the system (hopefully you already know that…)

Typical answers we received are summarized in the following table:

Question B-16: What does economical documentation mean?

Some tips for appropriate (economical or thrifty) documentation:

• Less (shorter) documentation can be often read and digested in shorter time (but beware of overly cryptic brevity, so no Perl, APG or regular expressions).
• Less documentation implies fewer future changes or modifications.
• Explicitly decide what kind and amount of documentation is appropriate, and with what level of detail.
• Differentiate between short-lived, volatile documentation (i.e. flipcharts for your project work) and long-lived system documentation. See [tip V-6]{#tip-v-6}
• Dare to leave gaps: Deliberately leave certain parts of your (arc42) documentation empty. Especially within arc42-section 8 (crosscutting concepts) you can often remove numerous subsections that might not be relevant for your specific system.

See question B-4 (Minimal amount of documentation)

VII.C Questions on arc42 sections

1. Requirements, quality-goals, stakeholder

Question C-1-1: How extensive shall I describe the requirements of the system?

So that readers of your (architecture) documentation can understand why the system exists and what its major requirements are.

• Briefly explain the major (max 3-5) use-cases, features or functions.
• Document the top 3-5 quality requirements by showing scenarios (see question C-10-2 (quality scenarios)).
• Make sure the most important domain terms are commonly understood among the development team (arc42 provides a glossary section for that purpose, but you better let your product owner or other stakeholders create and maintain those definitions.)
• Link to additional requirements documentation, if it exists.

Question C-1-2: What are quality goals (aka quality attributes)?

See also questions:

• C-10-2 (quality scenarios))
• C-10-3 (quality tree))

We use the term quality goals synonym to architecture goal:

A quality attribute that the system needs to achieve. These goals often have long term character in contrast to (short term) project goals.

Software quality in general is the degree to which a system possesses the desired combination of attributes (see: software quality).

Important quality attributes are performance, robustness, security, safety, flexibility, dependability, maintainability etc..

It’s helpful to distinguish between

• runtime quality attributes (which can be observed at execution time of the system),
• non-runtime quality attributes_ (which cannot be observed as the system executes) and
• business quality attributes (cost, schedule, marketability, appropriateness for organization)

Examples of runtime quality attributes are functionality, performance, security, availability, usability and interoperability.

Examples of non-runtime quality attributes are modifiability, portability, reusability, testability.

It sometimes helps to take a look at the (very generic) ISO-25010 software product quality tree, which summarizes most practically relevant potential quality goals on the abstraction level of “quality attributes (see below)

Question C-1-3: Why does arc42 propose a stakeholder table?

1. System stakeholders are potential consumers of information about the software or system architecture.
2. Several of the stakeholders might impose quality requirements on the system, that the development team needs to know about.
3. Architecture stakeholders are sometimes forgotten during conventional requirements analysis, e.g. dev-teams of external interfaces, auditors or developers themselves - these people or organizations will not have requirements concerning the system itself, but its architecture or architecture documentation.
4. Stakeholders are the most important source for any kind of feedback that can help you and the development team to evolve and improve the architecture…

Question C-1-4: What shall be included in a stakeholder table?

Bold information should be present, the other parts are optional.

Question C-1-5: What are the expected deliverables in the stakeholder table?

What documents, artifacts, deliverables, reports or other means of communication do stakeholders expect or require from the architecture or development team?

Please don’t confuse this with the system requirements.

Some examples might clarify the term:

• Developers of the fooBarexternal interface might expect a detailed description with sample data and code snippets, so they know how to implement this interface (explained in the building block view, arc42 section 5).
• All developers need to know how the system stores cost-relevant furpsdata into our auto-replicated NoSQL datastore (most likely explained in on of the crosscutting concepts in arc42 section 8)
• The product owner calls for a decision log of architecturally relevant decisions (arc42 section 9).
• Operation or administration need to know technical detail of the required database and middleware configuration.

2. Constraints

Question C-2-1: What are constraints?

Constraints restrict your freedom in decisions, concerning the system or any associated processes.

Such constraints are often imposed by organizations across several IT systems.

Examples:

• System has to be operated by data-center XYZ, as our company has a long-term contract with them.
• Part of software/hardware development has to be off-shored to our Asian subdivision.
• Our operational database system needs to be IBM DB2.

Please consider also questions C-2-2, C-2-3 and C-2-4.

Question C-2-2: What types of constraints exist?

Three major types of constraints exist:

• Organizational constraints: E.g. compliance to (standard) processes, budget, time, required information flows, required (management) reporting structures, adherence to certain documentation templates or conventions…
• Technical constraints: Usage of specific hardware, middleware, software-components, adherence to specific technical or architectural decisions (e.g. use of specific frameworks or libraries)
• Conventions, e.g. programming style, naming conventions or similar stuff.

Question C-2-3: What kind of constraints shall I document?

At first - try to avoid documentation of constraints, as somebody else might already have documented them. Refer or link to existing documentation.

Document the constraints that:

• shape or shaped important architectural or technical decisions,
• help people to better understand your architecture

Question C-2-4: Can/shall we negotiate constraints?

Should some constraints prove to be especially unfavorable, risky or even expensive for your system, you should definitely try to negotiate them.

An example: Let’s say the company-wide constraint is: “Our software has to be developed in Java”. One of your tasks is the development of a specific smart-card reader, including the appropriate hardware device driver - you should convince your management that such software is better written in either C, Forth or Lua.

3. Context

Question C-3-1: What is the context (scope)?

“The context defines the relationships, dependencies, and interactions between the system and its environment: People, systems, and external entities with which it interacts.”

Quoted from Rozanski-Woods

The context shows the complete system as one within its environment, either from a business perspective (business context) or from a technical or deployment perspective (technical context). The context view (or context diagram) shows the boundary between a system and its environment, showing the entities in its environment (its neighbors) with which it interacts.

It thereby identifies the system’s relevant external interfaces. Make sure that the interfaces are specified with all their relevant aspects (what is communicated, in which format is it communicated, what is the transport medium, …).

Question C-3-2: How shall I document the context (scope)?

Short answer

Combine a component diagram with a table. In that diagram, your system shall be a black box. All external interfaces (neighbor systems, user roles, participating actors and sensors) shall be visible.

Longer answer

Read the short answer above.

In case you have many neighbor systems (or external interfaces), you may categorize them by finding proper abstractions or generalizations. For example, for an e-commerce system your system will likely have external interfaces to numerous payment providers (credit card companies, banks etc). In the context diagram, you can combine all those into a single payment providerexternal interface, and defer the details to either a detailed building block level or even a payment privider concept.

Accompany your context diagram by a brief table, explaining the names/identifiers from the diagram. Refrain from too many details here, but refer or hyperlink to corresponding parts of your arc42 documentation.

See question C-3-7 (simplify documentation of business context) for some options of working more efficiently with the business context.

Question C-3-3: What is the “business context”?

All neighboring systems and business data that is exchanged with the system.

The business context should avoid overly technical information (like detailed protocol or data type information, communication channels or hardware information).

You find an example on the left side of the diagram below. Contrast it with the technical context of the right side of this image (described in question C-3-4 (technical context)).

Question C-3-4: What is the “technical context”?

Specification of the technical communication channels or protocols linking your system to neighboring systems and the environment.

You will find technology and physical infrastructure information in a technical context.

See also:

• the right part of the diagram above, in contrast to the business context on the left side of that diagram.
• question C-3-3 (business context)
• question C-3-6 (when to document technical context)

Question C-3-5: In which cases shall I document the “business context”?

Always (as in “in every single system you ever work on”).

There are, though, several options for you to save effort in documenting the business context - see question C-3-7 (simplify documentation of business context).

Question C-3-6: In which cases shall I document the “technical context”?

When hardware, protocols or deployment is of utmost importance for many stakeholders, then you can use the technical context to convey such information.

In most business systems you can ignore the technical context and document or specify that information in the deployment view in arc42-section 7.

Question C-3-7: How can I simplify documentation of the “business context”?

Some ideas:

• Reduce precision or the amount of detail you show in the business context. Show abstractions, aggregate neighbors or even interfaces.
• Show categories of neighbors, not every single neighbor system.
• Use UML port symbols on a component diagram to avoid drawing too many boxes and lines
• Combine multiple types of users or user-roles into appropriate abstractions or more generic roles (e.g. combine private and corporate users simply into “users”).

Question C-3-8: Shall I document risks or problems in the context?

External interfaces are especially sensitive to problems or risks, often functionality or availability of your system depends on some of these external interfaces.

Problems or risks associated with external interfaces therefore need special attention or countermeasures - so it’s a great idea to explicitly show those risks or problems in the context view.

Below you find some examples of risks or problems that might occur at external interfaces:

• Availability risk: if external systems are down: an external system heavily influences the availability of your system.
• Cost risk: the usage of an external system is expensive, individual calls or other types of use cost money. Examples are credit card checks or payment/booking services.
• Security risks: you receive/send sensible data from/to external systems. That could make these interfaces particularly interesting for a potential attacker.
• Volatility (high probability of change) of external systems: Interfaces of external systems are changed often (they are “work in progress”). The syntax and semantics of the transmitted data could be changed on short notice, which means that you either have effort adapting to these changes or you need to develop a flexible consumer for these interfaces.
• Complexity risks: using this interface is exceptionally complex or difficult, because it might have complex data structures, uses esoteric frameworks, complicated handshakes or an arbitrary mixture of those.

4. Solution strategy

Question C-4-1: What is the “solution strategy”?

A short summary and explanation of the fundamental solution ideas and strategies.

An architecture is often based upon some key solution ideas or strategies. These ideas should be familiar to everyone involved in architecture work.

Question C-4-2: How to document the “solution strategy”?

Short answer

As brief as possible. As many different stakeholders will read the “solution strategy”, its explanation shouldn’t be overly technical.

Longer answer

State these decisions which gravely influence(d) your architecture. Refrain from overly detailed explanation, don’t describe possible alternatives or even implementation guidelines.

You can (or should) dive into such technical detail in arc42 section 8 (crosscutting concepts), where you can elaborate on the how and why of your approaches. If only single building blocks are concerned, even the building block view (arc42 section 5) might be the appropriate location for this information.

Provide hyperlinks or at least references to sections or documents giving additional information or detail.

Question C-4-3: Can you provide examples for the solution strategy?

Yes - of course :-)

The following examples are taken from the arc42 by Example Leanpub book.

From the Html-Sanity-Checker example architecture

1. Implement HtmlSC mostly in the Groovy programming language and partially in Java with minimal external dependencies.
2. Wrap this implementation into a Gradle plugin, so it can be used within automated builds. Details are given in the Gradle userguide.
3. Apply the template-method-pattern to enable:
   • multiple checking algorithms. See the concept for checking algorithms,
   • both HTML (file) and text (console) output. See the reporting-concept.

(Remark: Some hyperlinks in the paragraph above might not work, as they were only meant to be examples.)

From a Mass-Market CRM system

(Remark: Again - no links to details are given in last column of the table - in any real architecture documentation you should prefer hyperlinks to just naming the sections. )

5. Building block view

Question C-5-1: What is a “building block”?

Short answer

Any piece of source code of your system.

Longer answer

Any programming or source code construct (e.g. module, component, subsystem, class, interface, package, library, framework, layer, partition, tier, function, macro, operation, data structure, …) that you implemented to make your system work.

Further examples of building blocks which might be relevant for your system:

• configuration files or items
• UI specific files, styles or definitions, like css-files in web development.
• Any kind of templates used to generate other artifacts at compile-, build- or runtime
• Build- or makefiles
• Deployment- or installation-related artifacts (e.g. deployment- or container descriptors)

Question C-5-2: Do third-party libraries, frameworks or tools count among building blocks?

Short answer

Limit building blocks to things you implement or maintain yourself.

Longer answer

Some external software (like middleware, database, UI-toolkit or similar) might be essential to understanding the structure of your system. You can include those in the building block view.

You definitely should show those elements in the deployment view (arc42-section 7)!.

Question C-5-3: How does source code relate to building blocks?

Short answer

Building blocks represent your source code. Your building blocks should be an abstraction of your source code.

The problem: There can be several possibilities how you can aggregate source code constructs to building blocks. I’m afraid you have to read the longer answer below…

Longer Answer

Mapping code to building blocks is a challenge, which we like to demonstrate by a small example, see the following figure. In its center you see a directory listing of (Python) source code files making up the system. Both on the left and the right side of the images you find different, but perfectly valid building block structures for these files.

Both versions were created with different abstraction criteria, both are possible.

In reality, you should organize your source code along your abstraction criteria. Some technologies or frameworks impose certain directory structures that can suggest completely different building block structures than those intended by the architects.

Especially layer structures (view, application, infrastructure) found in some technologies can obfuscate any business- or domain structures that could be useful in understanding the overall organization of the system.

Every single piece of source code should be contained in one of your level-1 building blocks.

Question C-5-4: How detailed shall we document the building block view?

Short answer

Show at least level-1, the top-level structure of the implementation.

Longer answer

As detailed as your stakeholders need it. In many cases, refining just a few of the top-level building blocks will be sufficient - with safety-critical system (as always) being an exception!

Question C-5-5: Can I refine a group of building blocks together?

Yes, sometimes it can be helpful (although it somewhat destroys the symmetrical structure of the building block hierarchy).

You find an example below:

Question C-5-6: How can I document or specify building blocks?

It depends on wether you need an overview (black box) or details (white box):

For the overview (black box), you should document or specify building blocks by giving the following information:

• Responsibility: What does this blackbox do, what task or function does it fulfill? What use-cases, use-case-clusters does it handle?
• Interface: What is the interface (input, output) of this blackbox, what is its API, what does it require as input and what does it provide as output.
• Source code: Where to find the source code of this blackbox. That might be the most important entry point, a number of files, directories or packages. Anything that might help a developer to find details.

We call this the black box template, see also question B-8 (black box template).

For details (white box), you should use a diagram with some explanation (aka white box template, see question B-9 (white box template).

Question C-5-7: How shall I document building blocks for non-object-oriented systems?

Wether object-oriented, procedural, functional or any other programming paradigm: Building blocks are an abstraction of your source code. You shall primarily describe or specify their respective responsibilities (and a few other details).

arc42 does not depend on a particular development approach or programming paradigm…

For other hints to describe or specify building block structures, see question C-5-6 (document building blocks).

Question C-5-8: How do I describe internal interfaces?

By internal interface we mean the interface between building blocks within a system, in contrast to external interfaces that connects our system to the external world.

You have a number of options, shown below with increasing degree of detail and effort:

1. Show the interface by any connection (line) within a whitebox diagram.
2. Give the interface a (hopefully self-describing) name (aka aptonym).
3. Describe the name informally (e.g. within a table below the respective whitebox diagram) with one or two sentences.
4. Document the interface and its usage by one or more unit-tests. The idea behind those tests should be “test-as-documentation”. On one hand these tests are precise, on the other hand they shouldn’t add much overhead to your work, as you will write some unit tests anyway (at least we hope so…)
5. Add the programming interface (API): list methods or functions with the required/optional parameters.
6. Add further UML details to your whitebox diagram, e.g. ball-socket, ports, and describe those within your modelling tool.
7. Add quality attributes of this interface to the API description, e.g. performance or throughput guarantees. Some people call those the “service level agreements” of the interface.

I like to emphasize the usefulness of test-as-documentation: It’s a developer-friendly and pragmatic way of documenting potentially critical elements of your architecture. Those tests will (hopefully) be automatically included into your documentation - so the documentation is always correct.

Question C-5-9: How do I describe external interfaces?

Basically similar to internal interfaces (see question C-5-8 (internal interfaces)).

The major distinction might be the fact that external people (beyond the scope and influence of your systems’ stakeholders) can be involved, both as consumers and as providers of interfaces (or data or events at these interfaces).

As these external people will likely not have access to your internal arc42 documentation, you might be required to provide distinct documents for your external interfaces.

Question C-5-10: How can I avoid redundancy with interfaces in the building block view?

Especially external interfaces might occur several times within the building block hierarchiy - how can I avoid to document or specify them at several places redundantly?

See the diagram below - the interface X (marked with red circles) occures three times in the hypothetical system shown there.

Handle such situations in the following manner:

1. In the context diagram, give the interface an appropriate name and briefly explain its business relevance or significance in just a few words.
2. Describe the interface in detail at the level where it is actually handled (e.g. the service is implemented or data is consumed). In the diagram above, this would be whitebox “B”.
3. At all other occurances (especially in the context view), add references to the detailed description. In the scenario above, such references should occur in the context and the level-1 whitebox.

Question C-5-11: How does the hierarchy of building blocks relate to the arc42 sections (5.1, 5.2 etc.)?

Short answer

Level-n of the building block view shall be documented in section 5-n of the building block view, where level-0 (zero) is the context view and level-1 your topmost system whitebox.

Longer answer

See the following diagram.

Question C-5-12: What kind of building blocks don’t I need to document or specify?

In case you want or need to save documentation effort, you have some good opportunities within the building block view. You can possibly omit the following kinds of building blocks from your documentation:

• Really small blocks that will easily be understood by reading the source code.
• Blocks that serve general purpose and are not specific to your system.
• Blocks that only apply (thoroughly defined) crosscutting concepts and don’t do much else.
• Blocks that implement purely technical functions, like persistence, logging, communication, data transformation, data validation or data dispatching.

Tendencially avoid documenting lower-level building blocks.

Question C-5-13: What kind of building blocks shall I document or specify?

This is the opposite of question C-5-12 (blocks you don’t need to document).

You should document or specify the following kinds of building blocks:

• The level-1 whitebox (aka the top-level decomposition of your system).
• Blocks adressing specific or important functionality.
• Blocks that adress important quality attributes of the system.
• Blocks that handle complicated or complex functionality.
• Blocks that mitigate or handle risks.
• Blocks that contain surprises or unusual ideas.
• Blocks that somehow deviate from the rest of the system.
• Blocks that deviate from typical developers’ expectation.
• Blocks that are required or important for creating business value.

Focus on higher-level building blocks. Level-1 should always be documented.

Remember to be lazy and document economically: Smaller documentation for fewer building blocks are easier and cheaper to maintain than large documentation for many blocks…

6. Runtime view

Question C-6-1: What is a runtime scenario?

The runtime view describes the behavior and interaction of the system’s building blocks with one or more scenarios.

A runtime scenario shows specific interactions or behaviors of building blocks or building block instances, either with each other or external elements.

It shows how the system fulfills certain tasks.

Question C-6-2: What do I document in the runtime view?

How the system executes, the dynamics of the system, its behavior in terms of its building blocks.

The following types of scenarios might be relevant for you:

• The most important use cases, features or functions
• System startup
• The systems´ behavior on its most important external interfaces
• The systems´ behavior in important error or failure situations

Question C-6-3: How can I describe scenarios or execution flows?

You have several options (many more than for the static building block view..). The following list is ordered by increasing documentation and maintenance effort. Options further down that list are more fine-grained and usually contain more details.

1. Document scenarios in plain text by enumerations or numbered lists. Include precise hints which building block executes which step(s) of use cases, processes or functions.
2. Use activity diagrams or flowcharts with swimlanes.
3. Use UML sequence diagrams. They are time-consuming to create and maintain with most interactive tools, but are an excellent means to show the mapping between building blocks and their actions. See question F-10 (tools for sequence diagrams) for some tips on tools.

UML has some additional options (e.g. state transition or object diagrams) to describe behavioral aspects of systems or building blocks. Those can be sometimes be useful, but are less often used that activity- or sequence diagrams.

Question C-6-4: What are partial scenarios?

Partial scenarios describe parts or extracts of complete scenarios or processes. They show only interesting, difficult, risky or important aspects of some greater process.

Concentrating on these essentials brings several benefits:

• You avoid trivial parts of scenarios
• You work more economically by leaving out unneccessary, non-important or low-priority aspects. That saves time/effort in creating and maintaining documentation!
• Smaller scenarios might be easier to understand (if (!) you make very clear which parts of the overall scenario you left out!)

A risk of partial scenarios might be consumers that don’t understand the prerequisites or preconditions of a partial scenario. Use annotations within your diagrams to explicitly clarify such required knowledge or facts.

In the figure shown below, you find a complete scenario first, and a nice partial scenario as an extract afterwards.

As you see, the first interactions seem quite trivial. Therefore, we can simple leave them out in a partial scenario:

|

Question C-6-5: Which scenarios shall I describe or document?

The following types of scenarios are candidates for runtime scenarios:

• The general case (aka the rule) of the most important use cases, features or functions.
• Important interactions with external systems, neighbours or user categories.
• Dynamic behavior of important external interfaces.
• Interactions that affect important quality goals or requirements.
• Error or failure conditions that might influence overall system behavior.
• Bootstrap-, startup or shutdown procedures, especially in distributed systems.
• Interactions that somehow deviate from normal stakeholder expectation, especially deviate from developer expectation.
• Interactions that work in non-standard ways.
• Scenarios or processes that are subject to timing constraints

7. Deployment view

Question C-7-1: What does the deployment view show?

1. Your hardware structure(s), also called technical infrastructure.
2. The mapping(s), also called deployment, of your software to this hardware.

For part 1, hardware, there might be several variants. Therefore part 2, deployment, might be different, depending on these hardware structures.

Question C-7-2: Why do I need a deployment view?

The deployment (mapping of software onto hardware elements) can be rather complicated, see the example in question C-7-5. See also the second part of question C-7-1 (deployment).

Question C-7-3: Who shall describe/document the deployment view?

The first part of the deployment view, (see question C-7-1 (deployment).) will sometimes be created and maintained by stakeholders responsible for technical infrastructure and/or hardware.

The second part, the mapping of software to hardware, will often be documented and maintained by architects and/or the development team.

Question C-7-4: Shall I use UML deployment diagrams for the deployment view?

The UML provides only this type of diagram for deployment and infrastructure, therefore you have no practical alternative.

On the other hand, you can of course use any free form of diagram to depict your technical infrastructure.

Make sure that stakeholders understand such notations - and that architecture- and infrastructure decisions can be understood based upon these diagrams.

Question C-7-5: Can there be different deployment scenarios or variants?

Yes, for example when you have different stages from development to your production environment.

See the following example, where the (static) building blocks A, B, C can be deployed in three different alternatives:

Question C-7-6: What shall I do when my building blocks get dynamically assigned an execution environment (node) - so I cannot statically assign them to infrastructure nodes?

If some part of your system or your infrastructure decides at runtime where a particular instance of a building block gets executed, then the deploment view should at least explain this behavior.

It might be useful to create a “dynamic deployment concept” in arc42 section 8 and refer to this concept from the deployment view.

8. Crosscutting concepts

Question C-8-1: What is a crosscutting concept?

We use the term “concept” for rules, principles or other decisions, guidelines, processes that influence one or more elements of the architecture.

• Decisions, or concepts that cannot adequatly be assigned to a single building block
• Decisions or rules that influence several
  • building blocks
  • parts of the implementation
  • runtime scenarios
  • interfaces
  • several developers

Question C-8-2: Our arc42 section 8 (on concepts) is a melting pot of information we couldn’t put elsewhere? How can we keep an overview?

The variety of topics in section 8 might seem chaotic, but all topics contained have something in common: They are all crosscutting (for an explanation, see question C-8-1 (what is crosscutting)).

You shall remove (!) all concepts not relevant for your system (see question C-8-3 (deal with many concepts)).

Then you can group/order the remaining topics, either to system-specific criteria or after the following proposal (based upon ideas by Stefan Zörner):

• Business or domain aspects: domain, entity or data models, the ubiquitous language from domain-driven design
• Architectural patterns: What (recurring) patterns have been applied, and how?
• Development: Build and build management, code generation, configuration, (automated) testing, migration
• Under the hood: persistence, distribution, transactions, session-handling, caching, threading, exception and error handling, security
• Interactions with users or external systems: user interface aspects, i18n, validation, accessibility, communication, integration
• Operations: deployment, installation, monitoring

Question C-8-3: How shall I deal with the multitude of potentially crosscutting topics?

At first, treat arc42 section 8 as a checklist and work iteratively:

1. Remove every topic that is not relevant for your system.
2. Prioritize the remaining subsections, criteria should be importance and risk.
3. Work on the highest priorities and briefly (!) document the corresponding decisions.

Many crosscutting concepts will be highly technical, therefore you document or specify those for developers. Source code with brief explanations can sometimes be sufficient - and can save you from writing awkward documents!

Question C-8-4: How shall I describe my business-/domain model?

You have several options, shown in order of increasing effort and degree-of-detail

1. Create an (tabular) glossary of relevant business terms.
2. Create an informal outline, where you show data types and their relationships. Define the terms in a glossary.
3. Create a data or entity model (either as UML class diagram or Entity-Relationship diagram), where you show business entities with their attributes and relationsships. Define the terms in a glossary.
4. Define a rich object model, where you add methods, functions or services to the entity model.
5. Work according to the Domain Driven Design (see [Evans-2004]): Create a ubiquitous domain language with several bounded contexts, model business entities and aggregates, use value objects, services, repositories and factories to enable communication within and about the domain. (Obviously this FAQ does not strive to provide detailed introduction to the fascinating topic of DDD, you have to look elsewhere⁷.)

Question C-8-5: Are there any general rules how to describe a concept?

Often developers (or other technical people) have to adhere or comply to concepts, or obey them. Therefore understandability, clarity, and applicability are primary goals, together with a shot of consistency, of course.

Some rules you might apply:

• Be practical and use source code examples to explain and demonstrate. Automated test can accompany the plain code, giving developers a feel how to do things.
• Write your concepts in the form of developer use cases”: “A developer wants to achieve XYZ” - and explain step by step what people have to do.
• Explain reasons why the concept is like it is. If you deviate from established standards or procedures, explain why and how you came to your solution.
• You can combine text with static and dynamic diagrams to describe your more complicated concepts.
• Describe the applicability: In which or for what cases shall the concept be applied?
• Describe the limits: In what cases, under which circumstances will the concept fail or cease to work?

9. Architectural decisions

In software engineering literature you find both “architecture decision” and “architectural decision”.

Question C-9-1: What kind of decisions shall I describe or document?

Describe or document the following kind of decisions:

• risky
• with expensive consequences
• with long-lasting effects
• affecting either
  • a large number of stakeholders
  • very special or important stakeholders
• that took a long time or much effort to decide
• astonishing

(document) architecturally significant” decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques.

Quoted from Michael Nygard

Question C-9-2: How can I document an architectural decision?

• Write a blog for your decisions, every decisions becomes a blog post.
• Use a text format similar to an (Alexandrian) pattern, like explained in question C-9-3 (Architecture Decision Record).
• For important decisions, the following topics might be interesting:
  • subject of the decision
  • affected stakeholders
  • decision criteria (with priorities)
  • alternatives
  • evaluation of alternatives for the various criteria
  • who took the decision?
  • reason for chosing this alternative in favor of others

Question C-9-3: What’s an Architecture Decision Record (ADR)?

In 2011 Michael Nygard proposed to document important architecture decisions in the following pattern-like format:

• Title: A short phrase with an ID, e.g. “ADR 9: LDAP for Multitenant Integration”
• Context: Forces at play, including technological, political, social, and project organizational. Forces might be conflicting.
• Decision: How do we deal with these forces, what do we do.
• Status: A decision may be “proposed” (if stakeholders haven’t yet agreed), or “accepted” (once it is agreed). Later it might be marked “deprecated” or “superseded” (you might include a reference to its replacement).
• Consequences: What happens after the decision has been applied. All consequences should be listed here, not just the “positive” ones. A particular decision may have positive, negative, and neutral consequences.

The ADR format lacks decision criteria, which I (Gernot) sometimes regard as really important… but maybe I’m prejudiced.

Question C-9-4: How can we handle a large number of architecture decisions?

Create a blog (RSS-feed) and write a brief entry for your important decisions. Tag those with labels (e.g.: frontend, backend, SAP-interface or similar), so stakeholders can filter them.

Such a blog shows the history of your system quite well. You can combine the blog with the idea of architecture decision records (see question C-9-3).

10. Quality scenarios

Question C-10-1: What is Software Quality?

(from IEEE Standard 1061): Software quality is the degree to which software possesses a desired combination of attributes. This desired combination of attributes need to be clearly defined; otherwise, assessment of quality is left to intuition.

Question C-10-2: What is a quality scenario?

Quality scenarios document required quality attributes. They help to describe required or desired qualities of a system, in pragmatic and informal manner, yet making the abstract notion of “quality” concrete and tangible.

• Event/stimulus: Any condition or event arriving at the system
• System (or part of the system) is stimulated by the event.
• Response: The activity undertaken after the arrival of the stimulus.
• Metric (response measure): The response should be measurable in some fashion.

There are different kinds of scenarios:

1. Usage scenarios: The system is used (any use case or system function is executed). Such scenarios describe how the system behaves in these cases, e.g. in terms of runtime performance, memory consumption, throughput or similar.
2. Change (or modification) scenarios: Any component within the system, its environment or its operational infrastructure changes or is being changed.
3. Failure scenarios: Some part of the system, its infrastructure or neighbors fail.

Question C-10-3: What is a quality tree?

(syn: quality attribute utility tree). A hierarchical model to describe product quality: The root “quality” is hierarchically refined in areas or topics, which itself are refined again. Quality scenarios form the leaves of these tree.

• Standards for product quality, like ->ISO 25010, propose generic quality trees. You find this generic quality tree in question C-1-2 (quality goals).
• The quality of a specific system can be described by a specific quality tree (see the example below).

Question C-10-4: Are there examples for quality scenarios?

• A new price calculation rule can be added to the pricing engine within 4 hours.
• The daily sales report for a single product category is generated within 10 seconds.
• When storage devices fail, the system gracefully shuts down (instead of crashing uncontrollably).
• The web client requires <5MB per browser session.
• Should the system run out of memory while processing the xyz algorithm, it will not crash, but will report the situation to an administrative user, stop the xyz process and return control to the interactive user within 30 seconds.

11. Risks and technical debt

Question C-11-1: What are risks and technical debt?

Short answer: The currently known problems.

Longer answer

The known risks (things that might become problems) and problems in the system, its related organizational, operational and development processes. They can refer to source code, structures, concepts, decisions and all other aspects of the system.

12. Glossary

You should ensure that all participating people have a common understanding of the important business (and technical) terminology which they use in context with the system.

The glossary is one manifestation of the general rule of “better explicit than implicit”.

VII.D Questions on modeling

Here we collect questions regarding UML and other modeling notations, plus general questions regarding understandability and consistency of models.

Question D-0: Why do I need a model? I have source code.

For cute, neat, small and mignion systems, you won’t need any model.

For larger, distributed, risky or otherwise complicated systems, architectural information in addition to source code can support both development and evolution of systems.

Models in our sense are arbitrary abstractions of architecture or architecture decisions, relating to either structure or (crosscutting) concepts.

Examples of such models we found useful:

• Context of the system, showing external neighbours and interfaces.
• Building blocks (e.g. subsystems, modules or such), representing potentially large chunks of source code.
• Other views, e.g. runtime or deployment
• A domain model, representing the core of your domain.

Models can be expressed using diagrams plus explanations, but might also be textual or tabular…

Question D-1: What alternatives to UML exist for architecture models?

Several alternatives compete with UML, the list below gives an overview (just an arbitrary selection, not exhaustive):

• informal box- and line diagrams. They can be helpful and are often ok, but please explain your notation, otherwise your diagrams are open for (mis-)interpretation.
• Fundamental-Modeling-Notation (FMC), an (academic) approach to communicate dynamic systems with block-diagrams, petri-nets and entity-relationship diagrams. See the FMC notation reference for details. FMC is rarely used in business or industrial systems, although it’s quite promising.
• SysML is an UML dialect, created to support systems engineering. Supported by numerous modeling tools, but in my opinion not practically relevant.
• Simon Browns pragmatic C4 model of software architecture description.

Question D-2: How to arc42 and UML relate to each other?

They don’t really need each other. You can very well use arc42 with and without UML.

Graphical modelling with UML does by no means make you a better architect, nor does it (automatically) improve your systems.

You might use UML to describe or specify the following aspects of your architecture:

• static structure (building block view)
• runtime behavior or runtime scenarios (runtime view)
• deployment or infrastructure

See also question B-3 (UML).

Question D-3: How can I use UML to communicate a hierarchy of building blocks?

Component- and package diagrams can communicate hierarchies, as both UML components and packages can be nested.

For examples, see

• question B-10 (building block hierarchy)
• question C-5-11 (hierarchy and arc42 sections)

Question D-4: How can I describe interfaces with UML?

The trivial option (usually not recommended): Just draw a line between two boxes to indicate that in interface between those two exist.

If you need more serious options, you have at least the following options (orderd by required effort for creating and maintaining such descriptions):

1. Give the line a label (to make it referencable) and explain its meaning in a table below the diagram. This should be sufficient for many non-safety-critical systems.
2. Use the provided/required notation (aka “ball/socket”), explicitely denoting which services/data/events the providing building block offers. There’s a nice explanation by Martin Fowler on this option.
3. Use distinct interface building blocks.
4. Use ball-and-socket notation in combination with port symbols.

The following figure shows options 1-4.

Question D-5: What can I use UML ports for?

Ports, these little rectancular boxes attached to components, packages or even nodes, represent an (optionally named) collection of interfaces. They come in handy for several reasons:

• Ports can support the detailed mapping of internal resp. external view of white- and blackboxes: Use ports to describe which internal building block of any whitebox communicates with an interface of the corresponding blackbox. In the following diagram, Foo communicates with Bar over a port. In the refining whitebox, the component BarA handles that interaction.

• I (Gernot) often used ports to denote the transmission protocoll for a particular interface: For an interface (e.g. inFoo) I can show that its available over http, https and ftp by attaching the same interface ball/socket to several ports, each port representing a distinct “access option” (ftp, http, https)…

  Note: This is not what the original inventors of UML intented…

• In hardware- and deployment diagrams, ports can represent input/output channels, network adapters, virtual networks, IP-addresses or similar .

Question D-6: How can I improve the understandability of my diagrams/models?

Understandable diagrams contain 5-15 elements with their relationships - normal people simply cannot grasp more than that number.

If you have overloaded or large diagrams, reduce the number of elements by abstraction:

• Aggregate several elements into a named blackbox. These elements should be cohesive, they should somehow belong together. The criteria should be an explicit decision.
• Refrain from showing loads of details, e.g. attributes or methods of single classes. Those details can often be left to source code.
• Especially in runtime scenarios, don’t always start with the beginning of a scenario, but dive-right-into the interesting parts.

Question D-7: How can I reduce the number of elements in a component /building block diagram?

See question D-6 (understandability).

Question D-8: How can I improve the consistency of models?

Consistency (or homogeneity) implies recognizability and often understandability. We like to explain it with the term “(inner) order”

Consistent systems or models treat identical situations in the same manner, coherent or uniform.

Consistency in models includes topics like layout, color, naming or uniform usage of symbols.

See also question D-6 (understandability)

VII.E Questions on arc42 and agile methods

The Agile Manifesto says: “Working software over comprehensive documentation”. It does not say “no documentation”.

Question E-1: Does arc42 work with Scrum, Kanban or other lean/agile approaches?

Yes, it surely does. arc42 is supposed to be used “on demand” - you provide only the type or amount of information required for your specific documentation purpose.

This interpretation fits nicely with lean and agile approaches - where you shall avoid waste and focus on fulfilling requirements… arc42 helps you to fulfill your documentation requirements easily in a pre-structured and well-thought-out way.

Question E-2: Shall our team make arc42 part of the definition of done (DoD)?

Yes, of course: If documentation is not part of the DoD, then it surely won’t be done.

Remember: arc42 proposes lean, economical and compact documentation that can be incrementally or iteratively enhanced.

Question E-3: How can arc42 help us in reducing documentation effort?

• Document crosscutting concepts instead of too many building blocks.
• Use abstractions in the building block view and runtime view.

Question E-4: We use Scrum. How can we integrate arc42 into our sprints?

Documentation shall be part of your Definition-of-Done. Therefore arc42 is automatically included in Scrum processes.

Question E-5: In agile projects, what kind of information shall we write down and what shall we communicate orally?

Imagine you’re a future stakeholder who then needs to work on the system (implement, architect, deploy, test, operate, monitor or other). Then ask yourself what information you need to have…

Question E-6: In agile projects, can we skip (defer) documentation for a while and focus only on implementing?

In theory, yes. In practice such a deferral means that this documentation will never ever be created - and stakeholders might need to dig deep into source code to gather the appropriate information.

We urge you - document economically (short, brief, compact), but do this continously.

Question E-7: What are the most important tips for documentation in agile projects?

• Even in a Scrum-team, appoint a person responsible for documentation. We like to call her/him the “The Docu-Gardener”, whos’ tasks shall be:
  1. care for the adequate form and content and
  2. proactively search for unnecessary or outdated parts and remove them. Please note: care does not mean your gardener shall create all content by her- or himself, but identify appropriate producers within the team or among associated stakeholders.
• Document economically (“Less is often more”): We really believe that documentation can be helpful and ease development work - but only in an extend and degree appropriate for the system and its stakeholders.
• Clarify appropriateness and needs through early feedback: The type of your documentation should be appropiate with respect to the system, the affected people, domain, risks, criticality, effort/cost and possibly even other factors.
• Focus on explanation and rationale, not only facts: Most facts about a software system can be found in its source code - but not their explanation, reasoning and rationale.
• Rate requirements higher than principles.

VII.F Questions on tools for arc42

As authors, we reserve the right to explain our personal experience and opinion. You should not base your tool selection solely on the information given here! There might be awesome tools available which we failed to mention…

Question F-1: What tools are well-suited for arc42?

This is a classical it depends type of question. Ask three different people, get at least five different (and most likely conflicting) answers…

• As arc42 documentation should always be a combination of text, tables and diagrams, a combination of different tools will often be a better choice than trying to get everything from a single tool (although tool vendors will tell you a different story)
• Often, (UML) modeling tools come with an abundance of functions and very limited usability. Their learning curve is high and might frustrate many. Overall, team acceptance tends to be low. Despite these usabilty shortcomigs we usually prefer real modeling tools over a pure graphics editor, especially for their better model consistency.
• Text processors (like Microsoft Word(R) or Open/Libre-Office) are omnipresent (practically all stakeholders can use them), but developers and other techies often don’t love them. Text processing tools provide limited team- and collaboration features, no real diff/merge, difficult to automate and are difficult to integrate with other tools. Nevertheless arc42 works with this category of tools without hassle.
• Plaintext-based approaches (like Markdown or AsciiDoc) in combination with graphics-tools (for smaller systems) or modelling tools (for medium to large systems) allow for documentation close-to-source-code and a high degree of automatability - therefore they tend to enjoy high acceptance with development teams.
• We love the combination of wiki plus graphics- or modelling tool. You can generate stakeholder-specific artifacts or pdf from modern wiki systems (like Confluence(R)).

Question F-2: What are useful criteria for selecting a toolset for arc42?

Some other criteria to watch out for:

• Teamwork: several people should be able to work in parallel
• Versioning: documentation artifacts need to be version-controlled. That’s quite easy for single files, but some modeling tools make versioning harder than it should be.
• Artifact generation: Sometimes you need beautiful or stakeholder-specific output (e.g. pdf, html). Some tools excel in this, others fail miserably.
• Robustness: You don’t want to re-create diagrams or documentation because your boss made you use that (supposedly) cheap free-and-open-source documentation tool… I had especially bad experiences with immature graphic/UML editors.)
• Availability of know-how: For several of the more common tools it’s quite easy to find people with corresponding experience. Some tool vendors provide excellent support, also in methodical questions.

Question F-3: Can I automatically include important code artifacts in arc42 documentation?

Short answer: Never (!) copy/paste code into your documentation - as it will be outdated before you hit the save key.

Longer answer (for AsciiDoc):

You can include code fragments be the following scheme:

[source,groovy]
----
include::{sourcedir}/Sample.groovy[lines=1;7..-1]
----

Instead of explicitely giving the line numbers in the include statements, you can annotate the corresponding source files with comment tags, as shown in the following example:

class Sample {
   // tag::helloMethod[]
   String hello() {
     'Asciidoc rules!'
   }
   // end::helloMethod[]
 }

and then reference this snippet in your documentation as follows:

[source,groovy]
----
include::Sample.groovy[tags=helloMethod]
----

See also the awesome blogpost from mrhaki and another on partial includes

Question F-4: How do I use arc42 with modeling tools?

Most modeling tools lack out-of-the-box arc42 support, you have to create your desired arc42 (sub-)structures by yourself.

arc42 does provide an empty arc42-structured model for Sparx Enterprise Architect(R), although not very elaborated.

We advice to restrict the use of modeling tools to the pure graphical part of architecture documentation, leave text and tables to other tools that are more suited for these kinds of information. In this case, create the following arc42-sections in your modeling tool:

• Context view
• Building block view
• Runtime view
• Deployment view
• Crosscutting concepts

Question F-5: How can I use arc42 together with Sparx Enterprise Architect(r)

<t.b.d.>

Question F-6: Are there (free or open-source) modeling tools available?

Short answer

In principal, yes. For example: * UMLet * Modelio * Violet

Longer answer

We have, at least until November 2016, not gotten to know any free modeling tool that can really compete with commercial tools with respect to robustness, useability, feature completeness and availability-of-know-how. Before you go for any free modeling tool, please make reasonably sure that your candidate fulfills the basic requirements we explained in Question F-2, concerning teamwork, robustness, versioning and artifact generation.

Actually, compliance to any specific UML standard is very often overrated.

Question F-7: Can we use arc42 with the Atlassian Confluence wiki?

Yes - it’s a (near-perfect) combination: Confluence⁸ is a powerful, yet easy-to-use collaboration platform, a “wiki-on-steroids”.

You can easyli map the arc42 structure on Confluence pages, and even use predefined templates to setup the complete arc42 structure in a breath (see question F-8 (Confuence tools) for details on available tooling).

In Confluence, you can tag (label, mark) pages, so it becomes very simple to add arbitrary meta-information to certain parts of your documentation. Use this e.g. to add version/release-specific information, or to distinguish between “already-implemented” and “planned-for-the-future” information.

Confluence does not (!) provide out-of-the-box diagramming features, but numerous tools are available to the rescue, see question F-9 (Confluence Diagramming tools) for details).

Question F-8: What tools can I use to setup arc42 in Confluence?

There a a few options to simplify the setup of the arc42 structure within your Confluence:

• The Networked-Assets ATC macro to insert the arc42 template into any Confluence space.
• The smartics Blueprints for arc42
• (Within the near future…) You can get a Confluence space generated out of the arc42 Golden Master from the arc42-template github repository. We’re currently working hard on making this available for download. Please contact us for a pre-release version if you’re interested.

See question F-9 (Diagrams in Confluence) for an overview of diagramming tools available for Confluence.

Question F-9: How can I create diagrams in Confluence?

• You can create and maintain your diagrams with any modeling tool and export your diagrams in jpg or png. Concluence can import these files, and will even keep a history of updates, if you ever upload newer versions. Beware: This requires maximal manual effort…
• You can create and maintain diagrams with a Confluence graphics plugin. I (Gernot) have positive experience with the following:
  • Gliffy, a well-known plugin for creating arbitrary diagrams within Confluence pages. The editor is complety integrated into the web browser. Supports different versions of diagrams, stable and robust, requires a commercial license.
  • Draw.io, a powerful browser-based graphics editor, also available as Confluence plugin. I (Gernot) have used the plain-browser version of draw.io - which can be used completely offline and export diagrams to various formats.

Question F-10: What tools shall I use for sequence diagrams?

Sequence diagrams (SDs) can be really useful to document or specify runtime scenarios, see question C-6-3 (how to document scenarios), but they are time-consuming to create and maintain with graphical modeling tools.

We will briefly discuss the following options:

• UML tools for SDs
• SDs generated by PlantUML from textual description
• SDs with browser apps

UML tool for sequence diagrams

With your favorite UML modeling tool, you can create and maintain sequence diagrams by dragging static building blocks onto the drawing canvas. When using these kind of tools, it’s relatively easy to maintain integrity between static and dynamic views, but the effort for creating diagrams is really high.

Sequence diagrams generated from textual description

PlantUML is a free tool that can render sequence diagrams from a textual description.

Consider an example: In the following listing you find the description of a simple sequence, shown in the figure below:

@startuml
G -> G : init
G -> H : sendEmail()
G <--H : reply X
G -> I : blabla( X )
I -> H : check( X )
I <--H : ok
@enduml

Charming: Such textual descriptions can be merged and versioned like any other source code!

PlantUML supports most UML SD constructs, like interaction references, loops, alternatives and so on. You can apply some styles to diagrams and export in several graphic formats (png, jpg, svg). There are numerous plugins available for wikis, development environments, build tools or the command line.

SDs build with browser apps

You may have a look at:

• DrawIO, an interactive (browser-based) graphic editor that can draw arbitrary (vector) graphics. Quite cool is the offline feature.
• Web-Sequence-Diagrams, similar to PlantUML, but only browser-based. For high-quality output, you need a (paid) subscription. The free online version can export png files. An example is given below:

title Authentication Sequence
Alice->Bob: Authentication Request
note right of Bob: Bob thinks about it
Bob->Alice: Authentication Response

Question F-10: Can I use PlantUML for building block / component diagrams?

Short answer

No, you should not use PlantUML for static diagrams - although you could. Read the longer answer for an explanation.

Longer answer

We really encourage the use of PlantUML for sequence diagrams (see question F-9 (Tools for sequence diagrams)), but don’t like it for static diagrams. That’s because in static diagrams we propose to carefully layout your building blocks, so that important elements are focussed, or elements somehow belonging together are drawn close to each other.

In PlantUML you can give formating hints, but the autolayout algorithms decide for themselves wether they can apply your suggestions or ignore them. I (Gernot) tried numerous times for real-world situations - and was always really unhappy with the results.

From my experience, static diagrams, like class- or component diagrams, look well only in hello-world like situations…

VII.G Questions on arc42 and versions / variants

Question G-1: Shall I version control our architecture documentation?

Yes, of course!. At best with the same strategy, processes and tools you use for your source code.

(Gernot’s opinion): If it’s not under version control, it does not exist (with the sole exception of well-managed wiki systems, that easily allow you to read older versions of documents.)

If you cannot use your version control system for your (architecture) documentation, see Question G-2.

Question G-2: We cannot use version control for documents. What to do?

Really (really!) make sure you find a (mostly automated) way to get your documentation under version control.

One way which helped me several times is the following:

• When you release your software (in continous deployment scenarios, you might stick to major releases…), create a pdf file from your documentation.
• Put this pdf under version control, in the same branch, tag/label or release info as your code-to-be-released.

Question G-3: How does versioning work with graphical models?

Although some tool vendors argue differently, recognizing the meaning of differences in diagrams imho requires human intelligence: I (Gernot) have not yet found any automatism supporting meaningful diff of diagrams or images. In my opinion somebody needs to care for new versions of diagrams.

It’s often a good idea to (automatically) include the modification date in a diagram (some modeling tools support this feature).

Question G-4: How can I describe several variants of a system?

<t.b.d.>

VII.H Questions on arc42 and traceability

Question H-1: What does traceability mean (with arc42)?

Full-scale traceability needs every single requirement to be referenced in any part of the architecture/solution documentation.

From a more pragmatical architectural (arc42) perspective, traceability can also refer to the understandability or explanation of important or fundamental architecture or solution decisions: “We took the decision Dec-X because of the requirements Req-Y.”

Question H-2: Shall we strive for traceability in our documentation?

Short answer

If you can, you should definitely avoid it: It’s horribly expensive, takes an awful lot of time and is really difficult.

Longer answer

In case you’re working in safety critical systems, like medical, pharmaceutical or avionics, you are most likely required to provide traceability.

One nice hook within arc42 are blackboxes within the building block view: Use the blackbox template to document:

• the requirements fulfilled or satisfied by this particular building block,
• the source code needed to implement this building block.

Question H-3: How can I keep architecture documentation in sync with source code?

We’ve several suggestions, but the most important one first:

• Document economically, especially be frugal with building block details: Many developers will understand many details of building blocks by digesting source code - so don’t create a large number of whitebox diagrams.
• Level-1 of the building block view will be one of your best friends: That top-level structure of your system will most often remain quite stable over time, and won’t need to be updated often. Many source code changes don’t affect level-1!
• Defer documentation of volatile parts: In case you can anticipate structural changes or volatility in certain parts of your system, leave the documentation of these parts as abstract and high-level as possible until these parts have reached a stable state.
• Prefer documenting “crosscutting concepts” (arc42 section 8) over detailed building blocks (section 5) or runtime scenarios (section 6).

VII.J Questions on managing documentation

Question J-1: How to document (very) large systems with arc42

Modularize extensive documentation:

Factor out (extract) documentation commonalities from different parts of the system and create separate documentation for relevant subsystems.

Link up these different parts of the documentation by hyperlinks, so that consumers can navigate freely between special and common parts.

A toolchain supporting modularization is an important prerequisite: it’s a nuisance with typical office products, but works quite smoothly with wikis or markup-languages.

For a schematic example of modularized documentation see figure arc42-modularized: The overall systems is made up from three subsystems. The common architecture documentation contains the introduction and goals, strategic decisions, building blocks level 1 plus crosscutting concepts. All these informations are valid and useful for the other three (smaller) documents.

Each subsystems’ documentation contains only parts of the arc42 template, and each subsystem focusses on different aspects.

The common part of your architecture documentation will most often contain the global system goals and the overall business context. Eventually it will also contain the solution strategy plus some crosscutting concepts.

Question J-2: Does a documentation governance make sense for architecture documentation?

It depends: On one hand, homogeneity, consistency and standardization can be really useful and efficient for documentation, on the other hand can cost and effort for such standardized documentation become very high.

Answer the following questions for your situation. The more “yes” answers the more useful a regulated documentation might be:

• Do you have many (i.e. more than 15) IT-systems you develop or maintain?
• Do many of these systems have technical similarities (use common frameworks, implementation approaches, technical concepts)?
• Do you work with different implementation or maintenance teams?
• Do you have a lot of change within your development team?
• Do different organizations work on your systems (i.e. external service providers)?
• Do you work in regulated domains (i.e. medicine, aerospace, pharmaceutics etc.)?
• Will the documentation of your systems be audited, validated or otherwise (formally) checked?
• Are some of your systems highly critical for success or survival of your organization?
• Are your systems maintained by a large development team (>100 people)?

Question J-3: Is there a checklist for arc42 documentation?

See question J-4.

Question J-4: Is there a general checklist for architecture documentation?

Counterquestion: What do you want to achieve with such a checklist?

• Improve the content of the documentation: You won’t get that by a checklist, but only by good examples, coaching and feedback.
• Checking formal criteria: Can you improve by checklists - but there’s no general consensus on formal criteria. We suggest you refrain from overly formal criteria - as documentation won’t get much more useful when it’s formal.
• You want to remind your team of some important parts of the documentation: Determine the subset of arc42 that your stakeholders really need - and then include those in your definition-of-done (see also question E-2 )

Question J-5: How can I create delta-documentation with arc42?

In other words: How can I document the changes (deltas) between two consecutive versions of a system?

<t.b.d.>

Question J-6: What level of access permissions shall stakeholders have on the architecture documentation?

Short answer

Keep the administrative effort as low as possible: If you accord details access permissions, you create administrative overhead.

Longer answer

Usually, all stakeholders can read and write the documentation. Some cases justify exceptions from this rule:

• For large teams, you should modularize your documentation and restrict write-access to certain parts, to avoid accidental changes.
• You might differentiate (short-term) project and (long-term) system documentation. Everybody can write in project documentation, only few people might modify system documentation.
• In case of regulated documentation, you might need detailed permissions (and access logs) to avoid manipulation.

VII.K Questions on customizing arc42

Question K-1: Are we allowed to customize arc42 for our (company/organization/system…) purpose?

Yes, of course. See Question A-2 (arc42 License).

You may modify the structure of the template, re-create it in any tool of your choice or even rename it for your own purpose (one of our clients called it SAT42, what we really enjoyed.)

To be fair, you should reference Gernot Starke and Peter Hruschka as creators of arc42 in case you use or modify the template…

Question K-2: What kinds of customizations are common for arc42?

Short answer

Customize or change arc42 only if you absolutely need to. The standardized structure of arc42 has a high recall value - many people are accustomed to it.

Longer answer

Keep arc42 modifications to subsections and leave the high-level structure unchanged.

I (Gernot) encountered the following modifications during real-world projects:

• User-interface view (UI-design, UI-forms, common layout etc). Sometimes, UI details can be highly relevant for other architectural aspects, e.g. handling application state, integrating with workflow technology or similar.
• Data view, explaining technical data models or concrete table structures. Often relevant in very data-centric organisations, where portfolios of applications are built around these data structures.
• Developer guide, containing detailed development information, sometimes called development use cases.

Appendix A: Further References and Resources

Agile Modeling

Scott Ambler: Agile Modeling. Tips and practices to pragmatic, agile modelling and documentation.

arc42

The template for software architectures, http://arc42.org (German website http://arc42.de)

arc42@Github

The arc42 Github repository: https://github.com/arc42/arc42-template. The (AsciiDoc) master version of the template is maintained here.

arc42 Examples of Quality Requirements

Examples for quality requirements with explanations and definitions: (currently only in German) https://github.com/arc42

ATAM,

Architecture Tradeoff Analysis Method. Systematic approach to evaluate the quality of software architectures by identifying risks and tradeoffs with respect to system-specific quality attributes.

Bass+2012

Bass, L/Clements, P/Kazman, R. Software Architecture in Practice, 3rd edition, Addison-Wesley, 2012. Although the title suggests otherwise, a quite fundamental (and sometimes abstract) book, written by members of the Software Engineering Institute. The authors have a strong background in ultra-large scale (often military) systems - so their advice sometimes conflicts with smaller kinds of projects. In our opinion it’s fundamental, but not very practical.

Brown2015

Brown, Simon. Software Architecture For Developers, https://leanpub.com/software-architecture-for-developers Technical leadership by coding, coaching, collaboration, architecture sketching and just enough up front design. Available on Leanpub. Readable, pragmatic and developer-oriented overview.

Buschmann+1996

Buschmann, Frank/Meunier, Regine/Rohnert, Hans/Sommerlad, Peter. A System of Patterns: Pattern-Oriented Software Architecture 1, 1st edition, 1996, John Wiley & Sons.

DeMarco+07

De Marco, Tom/Hruschka, Peter/Lister, Tim: Adrenaline Junkies and Template Zombies, http://www.amazon.com/Adrenaline-Junkies-Template-Zombies-Understanding, Dorset-House, 2007

Evans2004

Evans, Eric. Domain-Driven Design: Tackling Complexity in the Heart of Software, 1st edition, 20 August 2003, Addison-Wesley, 2003. The seminal and exhaustive work on constructing software with focus on the domain. One of my all-time favorite IT books, although you need some patience to read through it.

HtmlSanityChecker

A very small open source project to semantically check HTML files, e.g. for missing links, missing images, duplicate link targets and other kinds of errors.

Clements+2002

Clements, Paul/Kazman, Rick/Klein, Mark. Evaluating Software Architectures: Methods and Case Studies, Addison-Wesley, 2001.

Hargis+2004

Hargis, Gretchen/Carey, Michelle/Hernandez, Ann. Developing Quality Technical Information: A Handbook for Writers and Editors, IBM Press, 2nd edition, Prentice Hall, 2004. If you need to write lots of documentation, you should have a look at this book.

Hofmeister+2000

Hofmeister, Christine/Nord, Robert/Soni, Dilip. Applied Software Architecture, 1st edition, Addison-Wesley, 1999

Quian+2010

Qian, K/Fu, X/Tao, L/Xu, C/Herrera, J. Software Architecture and Design Illuminated, 1st edition, Jones and Bartlett, 2010. Well-structure and readable collection of architecture styles and patterns.

Appendix B: Also by This Author

If you liked the way we explained, communicated and documented software architectures, you might want to see more arc42 examples.

arc42 by Example

Also published on Leanpub, this collection of real-world systems, documented and explained with the proven and pragmatic arc42 template.

It contains the software architecture documentation of several concrete systems, how to improve your architecture communication and documentation: You find it on https://leanpub.com/arc42byexample.

iSAQB CPSA-Foundation Study Guide

Also published on Leanpub, this book helps you prepare for the iSAQB examination “Certified Professional for Software Architecture - Foundation Level”.

Appendix C: About Gernot Starke

Dr. Gernot Starke (innoQ Fellow) is co-founder and longstanding user of the (open source) arc42 documentation template. For more than 20 years he works as software architect, coach and consultant, conquering the challenges of creating effective software architectures for clients from various industries.

In 2008 Gernot co-founded the International Software Architecture Qualification Board (iSAQB e.V.) and since then supports it as an active member.

2014 he founded the (open source) Architecture Improvement Method aim42.

Gernot has authored several (German) books on software architecture and related topics.

Gernot studied computer science at the Institute of Technology in Aachen (RWTH Aachen) and finished with a Diploma. He then worked as a developer and consultant for smaller software companies, before coming back to university for international research on methodical software engineering. 1995 he received his PhD from Johannes Kepler University of Linz, Austria (Prof. Gerhard Chroust for his thesis on “Software Process Modeling”.

He then joined Schumann AG in Cologne and did consulting and development work for several years. He became technical director of the “Object Reality Center”, a joint-venture of Sun Microsystems and Schumann Consulting AG and lead the first European Java Project (the Janatol project for Hypobank in Munich).

Since then he has consulted and coached numerous clients from various domains, mainly finance, insurance, telecommunication, logistics, automotive and industry on topics around software engineering, software development and development process organization.

Gernot was an early adopter of the agile movement and has successfully worked as Scrum master in agile projects.

He lives in Cologne with his wife (Cheffe Uli) and his two (nearly grown-up) kids, two cats and a few Macs.

Email Gernot Starke or contact him via Twitter @gernotstarke.

Appendix D: Table of Tips

Here you find an overview of all tips contained in this book. The following table is generated⁹ from the complete book by parsing the markdown source.

Appendix E: Table of Questions

Here you find an overview of frequently asked questions. The following table is generated¹⁰ from the complete book by parsing the markdown source.

Notes