Introduction

Here you find answers to the most common questions regarding arc42, the proven, practical (free!) standard for documenting and communicating software architecture. These FAQ have been extracted from the book arc42 in practice (which itself is an enhanced translation from the German-language printed book arc42 in Aktion.

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:

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

The diagram below gives you the big picture: It shows a (slightly simplified) overview of the structure of arc42.

If you want to lean more about arc42: There are plenty of examples available.

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.

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.

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.

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)

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”.

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)

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.

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:

1 [source,groovy]
2 ----
3 include::{sourcedir}/Sample.groovy[lines=1;7..-1]
4 ----

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:

1 class Sample {
2    // tag::helloMethod[]
3    String hello() {
4      'Asciidoc rules!'
5    }
6    // end::helloMethod[]
7  }

and then reference this snippet in your documentation as follows:

1 [source,groovy]
2 ----
3 include::Sample.groovy[tags=helloMethod]
4 ----

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:

1 @startuml
2 G -> G : init
3 G -> H : sendEmail()
4 G <--H : reply X
5 G -> I : blabla( X )
6 I -> H : check( X )
7 I <--H : ok
8 @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:

1 title Authentication Sequence
2 Alice->Bob: Authentication Request
3 note right of Bob: Bob thinks about it
4 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…

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.>

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).

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.

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.

Related Books

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.

Communicating Software Architectures

This practical guide shows how you can effectively apply the practical and well-proven arc42 template to design, develop and document your software architecture.

It contains more than 200 practical tips how to improve your architecture communication and documentation:

• immediately actionable tips
• arc42 for practical software development
• effective communication and documentation of software architectures
• arc42 to construct, design and implement new systems
• arc42 to document existing system
• arc42 for { large | medium | small } systems
• tools for arc42: wikis, asciidoc, modeling tools an others
• frequently asked questions around arc42 (this FAQ-book is largely generated from this chapter of arc42-in-practice.)

You find it on https://leanpub.com/arc42inpractice.

arc42 in Aktion (German)

The German original of the previously mentioned eBook… for those who both understand German and like to hold printed books in their hands…

You get it at your local bookstore or online.

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”.

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.

Notes