Notes

1Table generated: November/24/2016↩

\n\n

2Eric Evans: Domain-Driven Design (Addision Wesley, 2004): The original source, 700+ pages of dense content. Vaugn Vernon, another veteran of DDD, has written “Domain-Driven Design Distilled” (Addision Wesley 2016), with only 170 pages - brief intro.↩

\n\n

3The name and logo of Confluence is copyrighted by Atlassian Software. arc42 is neither affiliated with or in any way sponsored by Atlassian Corporation.↩

\n\n\n

",{"_150":151,"_38":39,"_42":43,"_40":41,"_61":62,"_152":153,"_170":148},"previewContent","

\n Introduction\n
\n Table of Questions\n
\n Frequently Asked Questions\n
- \n A General questions\n
- \n B Questions on methodology\n
- \n C Questions on arc42 sections\n
- \n D Questions on modeling\n
- \n E Questions on arc42 and agile methods\n
- \n F Questions on tools for arc42\n
- \n G Questions on arc42 and versions / variants\n
- \n H Questions on arc42 and traceability\n
- \n J Questions on managing documentation\n
- \n K Questions on customizing arc42\n
\n
\n Related Books\n
\n About Gernot Starke\n
\n Notes\n

Introduction

\n\n

These (English) FAQ are currently in a quite early state.\nI’m translating them from their German original as fast as I can…

\n\n

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

\n\n\n

\n $\"\"$ \n

\n\n\n\n

arc42 is based on years of experience and used successfully since 2005 in many companies and\norganizations in different application domains.

\n\n

First of all arc42 is a template for architecture documentation.\nIt answers the following two questions in a pragmatic way:

\n\n

\nWhat should we document/communicate about our architecture?
\nHow should we document/communicate?

\n\n

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

\n\n\n

\n\n\n

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

\n\n\n

Table of Questions

\n\n

Here you find an overview of frequently asked questions. The following table\nis generated¹ from the complete book by parsing the markdown source.

\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

ID/Link	Questions
Question A-1	What does the 42 mean?
Question A-2	What’s the license?
Question A-3	What’s the pricing model of arc42?
Question A-4	How widely is arc42 used?
Question A-5	What’s the target audience of architecture documentation?
Question A-6	What are possible alternatives to arc42?
Question A-7	For what kinds of systems is arc42 applicable?
Question A-8	In which cases shall we NOT use arc42?
Question A-9	How can I contribute or report bugs in arc42?
Question B-1	Which parts of arc42 are “essential”, which are “optional”?
Question B-2	Does arc42 prescribe or enforce specific notations?
Question B-3	Shall I use UML for arc42 documentation?
Question B-4	What is the minimal amount of an arc42 documentation?
Question B-5	Where to document external interfaces?
Question B-6	How to document external interfaces?
Question B-7	Where to put links to external systems (“neighbors”) documentation?
Question B-8	What is a blackbox / the blackbox template?
Question B-9	What is a whitebox?
Question B-10	What is the building block hierarchy?
Question B-11	How to document a whitebox with the whitebox template\n
Question B-12	Where shall I describe important (blackbox) components?
Question B-13	Can I use arc42 in agile projects, e.g. with Scrum?
Question B-14	Can I update documentation incrementally? Or shall I document after the implementation is finished?
Question B-15	What kind of information shall I provide for which stakeholder?
Question B-16	What does economical documentation mean?
Question C-1-1	How extensive shall I describe the requirements of the system?
Question C-1-2	What are quality goals (aka quality attributes)?
Question C-1-3	Why does arc42 propose a stakeholder table?
Question C-1-4	What shall be included in a stakeholder table?
Question C-1-5	What are the expected deliverables in the stakeholder table?
Question C-2-1	What are constraints?
Question C-2-2	What types of constraints exist?
Question C-2-3	What kind of constraints shall I document?
Question C-2-4	Can/shall we negotiate constraints?
Question C-3-1	What is the context (scope)?
Question C-3-2	How shall I document the context (scope)?
Question C-3-3	What is the “business context”?
Question C-3-4	What is the “technical context”?
Question C-3-5	In which cases shall I document the “business context”?
Question C-3-6	In which cases shall I document the “technical context”?
Question C-3-7	How can I simplify documentation of the “business context”?
Question C-3-8	Shall I document risks or problems in the context?
Question C-4-1	What is the “solution strategy”?
Question C-4-2	How to document the “solution strategy”?
Question C-4-3	Can you provide examples for the solution strategy?
Question C-5-1	What is a “building block”?
Question C-5-2	Do third-party libraries, frameworks or tools count among building blocks?
Question C-5-3	How does source code relate to building blocks?
Question C-5-4	How detailed shall we document the building block view?
Question C-5-5	Can I refine a group of building blocks together?
Question C-5-6	How can I document or specify building blocks?
Question C-5-7	How shall I document building blocks for non-object-oriented systems?
Question C-5-8	How do I describe internal interfaces?
Question C-5-9	How do I describe external interfaces?
Question C-5-10	How can I avoid redundancy with interfaces in the building block view?
Question C-5-11	How does the hierarchy of building blocks relate to the arc42 sections (5.1, 5.2 etc.)?
Question C-5-12	What kind of building blocks don’t I need to document or specify?
Question C-5-13	What kind of building blocks shall I document or specify?
Question C-6-1	What is a runtime scenario?
Question C-6-2	What do I document in the runtime view?
Question C-6-3	How can I describe scenarios or execution flows?
Question C-6-4	What are partial scenarios?
Question C-6-5	Which scenarios shall I describe or document?
Question C-7-1	What does the deployment view show?
Question C-7-2	Why do I need a deployment view?
Question C-7-3	Who shall describe/document the deployment view?
Question C-7-4	Shall I use UML deployment diagrams for the deployment view?
Question C-7-5	Can there be different deployment scenarios or variants?
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?
Question C-8-1	What is a crosscutting concept?
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?
Question C-8-3	How shall I deal with the multitude of potentially crosscutting topics?
Question C-8-4	How shall I describe my business-/domain model?
Question C-8-5	Are there any general rules how to describe a concept?
Question C-9-1	What kind of decisions shall I describe or document?
Question C-9-2	How can I document an architectural decision?
Question C-9-3	What’s an Architecture Decision Record (ADR)?
Question C-9-4	How can we handle a large number of architecture decisions?
Question C-10-1	What is Software Quality?
Question C-10-2	What is a quality scenario?
Question C-10-3	What is a quality tree?
Question C-10-4	Are there examples for quality scenarios?
Question C-11-1	What are risks and technical debt?
Question D-0	Why do I need a model? I have source code.
Question D-1	What alternatives to UML exist for architecture models?
Question D-2	How to arc42 and UML relate to each other?
Question D-3	How can I use UML to communicate a hierarchy of building blocks?
Question D-4	How can I describe interfaces with UML?
Question D-5	What can I use UML ports for?
Question D-6	How can I improve the understandability of my diagrams/models?
Question D-7	How can I reduce the number of elements in a component /building block diagram?
Question D-8	How can I improve the consistency of models?
Question E-1	Does arc42 work with Scrum, Kanban or other lean/agile approaches?
Question E-2	Shall our team make arc42 part of the definition of done (DoD)?
Question E-3	How can arc42 help us in reducing documentation effort?
Question E-4	We use Scrum. How can we integrate arc42 into our sprints?
Question E-5	In agile projects, what kind of information shall we write down and what shall we communicate orally?
Question E-6	In agile projects, can we skip (defer) documentation for a while and focus only on implementing?
Question E-7	What are the most important tips for documentation in agile projects?
Question F-1	What tools are well-suited for arc42?
Question F-2	What are useful criteria for selecting a toolset for arc42?
Question F-3	Can I automatically include important code artifacts in arc42 documentation?
Question F-4	How do I use arc42 with modeling tools?
Question F-5	How can I use arc42 together with Sparx Enterprise Architect(r)\n
Question F-6	Are there (free or open-source) modeling tools available?
Question F-7	Can we use arc42 with the Atlassian Confluence wiki?
Question F-8	What tools can I use to setup arc42 in Confluence?
Question F-9	How can I create diagrams in Confluence?
Question F-10	What tools shall I use for sequence diagrams?
Question F-10	Can I use PlantUML for building block / component diagrams?
Question G-1	Shall I version control our architecture documentation?
Question G-2	We cannot use version control for documents. What to do?
Question G-3	How does versioning work with graphical models?
Question G-4	How can I describe several variants of a system?
Question H-1	What does traceability mean (with arc42)?
Question H-2	Shall we strive for traceability in our documentation?
Question H-3	How can I keep architecture documentation in sync with source code?
Question J-1	How to document (very) large systems with arc42
Question J-2	Does a documentation governance make sense for architecture documentation?
Question J-3	Is there a checklist for arc42 documentation?
Question J-4	Is there a general checklist for architecture documentation?
Question J-5	How can I create delta-documentation with arc42?
Question J-6	What level of access permissions shall stakeholders have on the architecture documentation?
Question K-1	Are we allowed to customize arc42 for our (company/organization/system…) purpose?
Question K-2	What kinds of customizations are common for arc42?

\n\n\n

Frequently Asked Questions

Category	Section	Keywords
General	A	Cost, license, contributing
Methodology	B	minimal amount of documentation,
		where-does-what-info-belong,
		notations, UML
arc42 sections	C	quality requirements, context,
		building blocks, runtime scenarios,
		deployment, concepts etc.
Modelling	D	UML, diagrams, interfaces, ports
		understandability, consistency,
		clarity
arc42 and Agility	E	Scrum, Kanban, definition-of-done
		minimal, lean, economical
Tools	F	Tools and their application,
		source code and documentation
Versioning and	G	versioning documents,
Variants		variants of systems

Traceability	H	tracing requirements to solution
		decisions and vice-versa
Management	J	very large systems, standardization,
		governance, checklists, access-rights
Customizing	K	tailoring and customizing,
		known adaptions of arc42

\n\n

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

\n\n\n

A General questions

\n\n

Question A-1: What does the 42 mean?

“42” is a quotation from the science-fiction novel\nHitchhikers Guide to the Galaxy\nby the famous Douglas Adams.

\n\n

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:

\n\n\n\n

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

\n\n

Question A-2: What’s the license?

\n\n

Creative-Commons Sharealike 4.0

\n\n

Under this license, you’re free to:

\n\n

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

\n\n

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

\n\n

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.

\n\n

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

\n\n

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

\n\n

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

\n\n

Question A-4: How widely is arc42 used?

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

\n\n

In these countries, alternatives like Simon Browns’\nSA4D/C4 model\nare not well-established.

\n\n

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

\n\n

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

\n\n

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

\n\n

Short answer: (Potentially) all stakeholders of a system, that require information\nabout the architecture, e.g. the internal structure, crosscutting concepts\nor fundamental decisions.
Longer answer: Which persons or roles are interested in what parts of the architecture\ndepends on the specific context. Some typical targets for such documentation:

\n\n

Software developers who actually implement within the system.
Software developers of neighbour systems, who need to know about\nexternal 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\nthe system for specific infrastructure needs, optimize it or perform administrative\ntasks requiring architectural understanding. This often includes security relevant\ntasks, 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\nto assess or evaluate the system.
Testers and QA-engineers who need to plan, impelement or perform\nwhitebox-, performance- or security testing.
Consumers of services offered by the system, in case they need to understand\nadditional details apart from the interface (blackbox) specification.

\n\n

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

\n\n

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

\n\n

Simon Brown’s SA4D/C4 model.\nYou find a brief introduction in one of his blog posts\n
\nThe View-Model\nof Paul Clements et. al from the Software Engineering Institute.\nFrom our point of view, their approach is very heavyweight and can become quite\nformal 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\ninformation about building blocks and crosscutting concepts. If it does, you’re pretty\nclose to arc42 anyway…

\n\n

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

Short answer: Due to its flexibility concerning tools, processes and extend, arc42\nis well-suited for all kinds of IT-systems (small to large, simple to complex,\nall kinds of implementation technologies).
Longer answer: For highly-critical systems, (e.g. safety-critical systems, where health\nor 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).

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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.

\n\n\n\n\n

B Questions on methodology

\n\n

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

\n\n

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\neffort in the future. With every piece of documentation, you’re\neffectively piling up maintenance debt - and in parallel creating some information value…\n
Please only document things, facts and reasons that you\nor your stakeholders consider important enough to justify\nwritten documentation.
\n

\n\n

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

\n\n

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

\n\n

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

\n\n

You don’t need to - but:

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

See question D-4.

\n\n

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

\n\n

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:\n

3-5 central quality requirements, expressed in\nscenarios.
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.

\n\n

Question B-5: Where to document external interfaces?

\n\n

Short answer

Both scope/context (arc42 section 3) and\nbuilding block view (arc42 section 5) provide adequate room\nfor external interfaces.

Longer answer

How and where you describe external interfaces depends\non several factors:\n

If your system provides external interfaces to external\nconsumers and you and your team can decide about\nany details of these interfaces - then you have to\ncare for their documentation.
Do you need to provide external systems with information\non how to use your interfaces? You could provide\nexample code and other interface documentation, but need\nto make sure this information is easily accessible to\nthe external stakeholders.
Do you just provide data at your external interfaces,\nand 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,\nmake sure their documentation is easily accessible by your\ndevelopment and maintenance teams. Include references in the arc42 context or building block view.

\n\n

Question B-6: How to document external interfaces?

\n\n

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.\nAdd some unit tests and/or other example code.

\n\n

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

\n\n

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

\n\n

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

\n\n\n\n

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

\n\n

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.

\n\n

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

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

part	explanation
Name	name or id of this blackbox. The name should be the title of the blackbox template.
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.
Qualities	What quality requirements does this blackbox satisfy? How fast/secure/robust is it? Does it offer any guarantees or service-level-agreements?
Open issues	Are there known issues, problems or risks associated with this blackbox?
Requirements	What are the requirements satisfied by this blackbox? Such information is important if you need traceability. See section H (Traceability)\n

\n\n

Question B-9: What is a whitebox?

\n\n

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

\n\n\n

\n\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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.

\n\n

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

\n\n\n

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

\n\n

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

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

part	explanation
Diagram	Shows the contained blackboxes plus their relationships
Rationale	The reason why this whitebox is structured like it is.
Contained blackboxes	Names and responsibilities of contained blackboxes, plus references to their detailed description.
Internal relationships (interfaces)	Brief description of the relationships between internal blackboxes, plus references to their detailed description.
Risks and issues	Know issues or risks with this whitebox, information about eventual technical debt or ideas for improvement

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

Yes, of course. See also:

\n\n

\nsection E (Agile),\nespecially question E-1 (arc42 and agile methods).
Question B-16 (economical documentation)

\n\n

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

\n\n

Short answer

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

Longer answer

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

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

\n\n

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

\n\n

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

\n\n

Short answer

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

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

Longer answer

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

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

\n\n

Typical answers we received are summarized in the following table:

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Stakeholder	Required information/artifacts
Project management	Quality goals, (business) context with external interfaces, solution strategy (most important architectural decisions), building block view level-1, overview of important concepts. Sometimes an overview of infrastructure and deployment.
Top- or upper management	Top-3 quality goals, major business requirements, business context with neighbor systems, compliance to IT strategy, compliance to security (and maybe other) standards, operation/deployment concepts, cost-relevant architectural decisions.
Product owner	Quality goals, building block view with interfaces, overview of important architectural decisions, overview of crosscutting concepts, known issues and risks
Software developers	Quality goals with detailed scenarios, solution strategy with links to detailed concept descriptions and/or example solutions, building block view with interface descriptions, important runtime scenarios, domain model, crosscutting concepts, deployment view with possible variants, glossary.
Operators, administrators	Infrastructure and deployment, external interfaces with technical and organizational details, logging and monitoring concepts.
Tester, QS-team	Detailed business and quality requirements, solution strategy, building blocks with interfaces, crosscutting concepts influencing testing or testability.
Developers of neighbor systems	Business and/or technical context, details description of external interfaces, end-to-end interaction/runtime scenarios at these interfaces.

\n\n

Question B-16: What does economical documentation mean?

\n\n

Some tips for appropriate (economical or thrifty) documentation:

\n\n

Less (shorter) documentation can be often read and digested in shorter time\n(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\nwith what level of detail.
Differentiate between short-lived, volatile documentation (i.e. flipcharts for\nyour 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.\nEspecially within arc42-section 8 (crosscutting concepts) you can often remove numerous subsections\nthat might not be relevant for your specific system.

\n\n

See question B-4 (Minimal amount of documentation)

\n\n\n\n\n

C Questions on arc42 sections

\n\n

1. Requirements, quality-goals, stakeholder

\n\n

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

\n\n

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

\n\n

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\namong the development team (arc42 provides a glossary section for that purpose,\nbut you better let your product owner or other stakeholders create and maintain\nthose definitions.)
Link to additional requirements documentation, if it exists.

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Information	Meaning
Name/Role	who or which part of an organization has an interest in the system or its architecture? Sometimes you name specific people, quite often you’ll stick to roles
Knowledge	What do these stakeholders know about the system or its associated processes?
Expected deliverables	What do these stakeholders expect from the architecture or its documentation? Please don’t confuse this with the system requirements. See question C-1-5 (deliverables) below.
\nRelevance (priority)	This is critical information: Some stakeholders will relevant or required for production acceptance or sign-off - but: Explicitly stating relevance or priority might frustrate, irritate or even instigate those with lower priorities… You need to consider the political consequences of putting this information in your documentation - but the team should definitely know about stakeholders’ relevance.
Contact	As trivial as a phone number or email address, so you or the team can contact this stakeholder.
Comment	Any other information people might need concerning this stakeholder.

\n\n

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

\n\n

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

\n\n

Please don’t confuse this with the system requirements.

\n\n

Some examples might clarify the term:

\n\n

Developers of the fooBarexternal interface might expect\na detailed description with sample data and code snippets,\nso they know how to implement this interface (explained\nin the building block view, arc42 section 5).
All developers need to know how the system stores cost-relevant\nfurpsdata into our auto-replicated NoSQL datastore (most likely\nexplained 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\nof the required database and middleware configuration.

\n\n

2. Constraints

\n\n

Question C-2-1: What are constraints?

\n\n

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

\n\n

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

\n\n

Examples:

\n\n

System has to be operated by data-center XYZ, as our company has\na 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.

\n\n

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

\n\n

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

\n\n

Three major types of constraints exist:

\n\n

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\nto specific technical or architectural decisions (e.g. use of specific frameworks or libraries)
Conventions, e.g. programming style, naming conventions or similar stuff.

\n\n

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

\n\n

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

\n\n

Document the constraints that:

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n\n

3. Context

\n\n

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

\n\n

\n
“The context defines the relationships, dependencies, and interactions between the system and its environment: People, systems, and external entities with which it interacts.”
\n\n
Quoted from Rozanski-Woods
\n

\n\n

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

\n\n

It thereby identifies the system’s relevant external interfaces.\nMake 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, …).

\n\n\n\n

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

\n\n

Short answer

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

Longer answer

Read the short answer above.\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n\n

\"Business — Business and technical context (of a simple web shop)

\n\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n\n\n

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

\n\n

Some ideas:

\n\n

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\nabstractions or more generic roles (e.g. combine private and corporate users simply into “users”).

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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.

\n\n\n\n\n

4. Solution strategy

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

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

\n\n

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

\n\n\n\n

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

\n\n

Yes - of course :-)

\n\n

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

\n\n

From the Html-Sanity-Checker example architecture

\n\n

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

\n\n

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

\n\n

From a Mass-Market CRM system

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Goal/Requirement	Architectural Approach	Details
Flexible Data Structure	Database structure + persistence code is completely (100%) generated from UML-model	Persistence concept, section 8.1
Flexibility in Transmission Formats (CSV and fix-record-formats	Create domain-specific languages for CSV and fix-format import/export configurations. Build an ANTLR based parser for these languages plus the corresponding interpreters.	Custom Eclipse Editor, Section 8.2
Flexibility (Configurable CSV/fix formats)	Implement customized editor for CSV/fix DSL as Eclipse plugin	Custom Eclipse Editor, Section 8.2

\n\n

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

\n\n\n

5. Building block view

\n\n

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

\n\n

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

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

\n\n

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

\n\n

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

\n\n

Short answer: Limit building blocks to things you implement or maintain yourself.
Longer answer: Some external software (like middleware, database, UI-toolkit or similar)\nmight be essential to understanding the structure of your system. You can\ninclude those in the building block view.\n
You definitely should show those elements in the deployment view\n(arc42-section 7)!.
\n

\n\n

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

\n\n

Short answer: Building blocks represent your source code. Your building blocks\nshould be an abstraction of your source code.\n
The problem: There can be several possibilities how you can\naggregate source code constructs to building blocks. I’m afraid you\nhave to read the longer answer below…
\n
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\nyou see a directory listing of (Python) source code files making up the system.\nBoth on the left and the right side of the images you find different, but perfectly valid building block structures for these files.

\n\n\n

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

\n\n

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

\n\n

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

\n\n\n\n

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

\n\n

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

\n\n

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!

\n\n\n\n

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

\n\n

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

\n\n

You find an example below:

\n\n\n

\"Refine — Refine two blackboxes togegher

\n\n\n

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

\n\n

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

\n\n

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

\n\n

\nResponsibility: What does this blackbox do, what task or function does it fulfill? What use-cases, use-case-clusters does it handle?
\nInterface: 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.

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

Show the interface by any connection (line) within a whitebox diagram.
Give the interface a (hopefully self-describing) name (aka aptonym).
Describe the name informally (e.g. within a table below the respective whitebox diagram) with one or two sentences.
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…)
Add the programming interface (API): list methods or functions with the required/optional parameters.
Add further UML details to your whitebox diagram, e.g. ball-socket, ports, and describe those within your modelling tool.
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.

\n\n

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.

\n\n

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

\n\n

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

\n\n

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

\n\n

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.

\n\n\n\n

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

\n\n

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?

\n\n

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

\n\n\n

\n\n\n

Handle such situations in the following manner:

\n\n

In the context diagram, give the interface an appropriate name and briefly explain its business relevance or significance in just a few words.
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”.
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.

\n\n

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

\n\n

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.

\n\n\n

\"Mapping — Mapping of building block hierarchy to arc42 sections

\n\n\n

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

\n\n

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:

\n\n

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.

\n\n

Tendencially avoid documenting lower-level building blocks.

\n\n

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

\n\n

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

\n\n

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

\n\n

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.

\n\n

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

\n\n

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…

\n\n\n

6. Runtime view

\n\n

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

\n\n

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

\n\n

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

\n\n

It shows how the system fulfills certain tasks.

\n\n

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

\n\n

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

\n\n

The following types of scenarios might be relevant for you:

\n\n

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

\n\n\n\n

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

\n\n

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

\n\n

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.
Use activity diagrams or flowcharts with swimlanes.
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.

\n\n

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.

\n\n

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

\n\n

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

\n\n

Concentrating on these essentials brings several benefits:

\n\n

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

\n\n

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.

\n\n

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

\n\n\n

\"Long — Long and mostly boring scenario

\n\n\n

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

\n\n

$\"Corresponding$ |

\n\n

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

\n\n

The following types of scenarios are candidates for runtime scenarios:

\n\n

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

\n\n\n

7. Deployment view

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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.

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n\n\n

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

\n\n

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

\n\n

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

\n\n\n

\n\n\n

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?

\n\n

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.

\n\n

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

\n\n\n\n\n

8. Crosscutting concepts

\n\n

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

\n\n

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

\n\n

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

\n\n

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?

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n\n

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!

\n\n

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

\n\n

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

\n\n

Create an (tabular) glossary of relevant business terms.
Create an informal outline, where you show data types and their relationships. Define the terms in a glossary.
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.
Define a rich object model, where you add methods, functions or services to the entity model.
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².)

\n\n\n\n

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

\n\n

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.

\n\n

Some rules you might apply:

\n\n

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?

\n\n\n

9. Architectural decisions

\n\n

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

\n\n

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

\n\n

Describe or document the following kind of decisions:

\n\n

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

\n\n

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

\n\n

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

\n\n

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:\n
- 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
\n

\n\n

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

\n\n

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

\n\n

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.

\n\n

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

\n\n

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

\n\n

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.

\n\n

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

\n\n

10. Quality scenarios

\n\n

Question C-10-1: What is Software Quality?

\n\n

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

\n\n

Question C-10-2: What is a quality scenario?

\n\n

Quality scenarios document required quality attributes.\nThey help to describe required or desired qualities of a system, in pragmatic and\ninformal manner, yet making the abstract notion of “quality” concrete and tangible.

\n\n\n

\"Generic — Generic form of (Quality) scenario

\n\n\n

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.

\n\n

There are different kinds of scenarios:

\n\n

Usage scenarios: The system is used (any use case or system function is executed).\n Such scenarios describe how the system behaves in these cases, e.g. in terms of\n runtime performance, memory consumption, throughput or similar.
Change (or modification) scenarios: Any component within the system, its environment\n or its operational infrastructure changes or is being changed.
Failure scenarios: Some part of the system, its infrastructure or neighbors fail.

\n\n

Question C-10-3: What is a quality tree?

\n\n

(syn: quality attribute utility tree). A hierarchical model to describe\nproduct quality: The root “quality” is hierarchically refined in areas or\ntopics, which itself are refined again. Quality scenarios form the leaves of\nthese tree.

\n\n

Standards for product quality, like ->ISO 25010, propose generic\n quality trees. You find this generic quality tree in\n question C-1-2 (quality goals).
The quality of a specific system can be described by a specific\n quality tree (see the example below).

\n\n\n

\n\n\n

Question C-10-4: Are there examples for quality scenarios?

\n\n

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.

\n\n

11. Risks and technical debt

\n\n

Question C-11-1: What are risks and technical debt?

\n\n

Short answer: The currently known problems.

\n\n

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,\ndecisions and all other aspects of the system.

\n\n\n\n

12. Glossary

\n\n

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.

\n\n

The glossary is one manifestation of the general rule of “better explicit than implicit”.

\n\n\n\n\n

D Questions on modeling

\n\n

Here we collect questions regarding UML and other modeling notations, plus general questions regarding understandability and consistency of models.

\n\n

Question D-0: Why do I need a model? I have source code.

\n\n

For cute, neat, small and mignion systems, you won’t need any model.

\n\n

For larger, distributed, risky or otherwise complicated systems, architectural\ninformation in addition to source code can support both development and\nevolution of systems.

\n\n

Models in our sense are arbitrary abstractions of architecture or\narchitecture decisions, relating to either structure or (crosscutting) concepts.

\n\n

Examples of such models we found useful:

\n\n

Context of the system, showing external neighbours and interfaces.
Building blocks (e.g. subsystems, modules or such), representing potentially\nlarge chunks of source code.
Other views, e.g. runtime or deployment
A domain model, representing the core of your domain.

\n\n

Models can be expressed using diagrams plus explanations, but might also\nbe textual or tabular…

\n\n

Question D-1: What alternatives to UML exist for architecture models?

\n\n

Several alternatives compete with UML, the list below gives an overview\n(just an arbitrary selection, not exhaustive):

\n\n

informal box- and line diagrams. They can be helpful and are often ok, but\nplease explain your notation, otherwise your diagrams are open for\n(mis-)interpretation.
Fundamental-Modeling-Notation (FMC), an (academic) approach to communicate\ndynamic systems with block-diagrams, petri-nets and entity-relationship diagrams.\nSee the FMC notation reference\nfor details. FMC is rarely used in business or industrial systems, although\nit’s quite promising.
\nSysML is an UML dialect, created to support systems engineering.\nSupported by numerous modeling tools, but in my opinion not practically relevant.
Simon Browns pragmatic C4 model of\nsoftware architecture description.

\n\n

Question D-2: How to arc42 and UML relate to each other?

\n\n

They don’t really need each other. You can very well use arc42\nwith and without UML.

\n\n

Graphical modelling with UML does by no means make you a better architect,\nnor does it (automatically) improve your systems.

\n\n

You might use UML to describe or specify the following aspects of your\narchitecture:

\n\n

static structure (building block view)
runtime behavior or runtime scenarios (runtime view)
deployment or infrastructure

\n\n

Question D-3: How can I use UML to communicate a hierarchy of building blocks?

\n\n

Component- and package diagrams can communicate hierarchies, as both UML components and packages can be nested.

\n\n

For examples, see

\n\n

Question D-4: How can I describe interfaces with UML?

\n\n

The trivial option (usually not recommended):\nJust draw a line between two boxes to indicate that in interface between those two exist.

\n\n

If you need more serious options, you have at least the following\noptions (orderd by required effort for creating and maintaining such descriptions):

\n\n

Give the line a label (to make it referencable) and explain its meaning\nin a table below the diagram. This should be sufficient for many non-safety-critical systems.
Use the provided/required notation (aka “ball/socket”), explicitely\ndenoting which services/data/events the providing building block offers. There’s a nice\nexplanation by Martin Fowler on this option.
Use distinct interface building blocks.
Use ball-and-socket notation in combination with port symbols.

\n\n

The following figure shows options 1-4.

\n\n\n

\"Various — Various options for interfaces in UML

\n\n\n

Question D-5: What can I use UML ports for?

\n\n

Ports, these little rectancular boxes attached to components, packages or even nodes,\nrepresent an (optionally named) collection of interfaces. They come in handy for\nseveral reasons:

\n\n

Ports can support the detailed mapping of internal resp. external view of white-\nand blackboxes: Use ports to describe which internal building block of any\nwhitebox communicates with an interface of the corresponding blackbox. In the following\ndiagram, Foo communicates with Bar over a port. In the refining whitebox,\nthe component BarA handles that interaction.

\n\n\n

\"Ports — Ports to show mapping between blackbox and its refinement

\n\n\n

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)…\n
Note: This is not what the original inventors of UML intented…
\n

\n\n\n

In hardware- and deployment diagrams, ports can represent input/output channels, network adapters, virtual networks, IP-addresses or similar .

\n\n

Question D-6: How can I improve the understandability of my diagrams/models?

\n\n

Understandable diagrams contain 5-15 elements with their relationships - normal people simply cannot grasp more than that number.

\n\n

If you have overloaded or large diagrams, reduce the number of elements by abstraction:

\n\n

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.

\n\n

Question D-7: How can I reduce the number of elements in a component /building block diagram?

\n\n

See question D-6 (understandability).

\n\n

Question D-8: How can I improve the consistency of models?

\n\n

Consistency (or homogeneity) implies recognizability and often understandability. We like to explain it with the term “(inner) order”

\n\n

Consistent systems or models treat identical situations in the same manner, coherent or uniform.

\n\n

Consistency in models includes topics like layout, color, naming or uniform usage of symbols.

\n\n

\n\n\n\n\n

E Questions on arc42 and agile methods

\n\n

The Agile Manifesto says: “Working software over comprehensive documentation”. It does not say “no documentation”.

\n\n

Question E-1: Does arc42 work with Scrum, Kanban or other lean/agile approaches?

\n\n

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.

\n\n

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.

\n\n

Question E-2: Shall our team make arc42 part of the definition of done (DoD)?

\n\n

Yes, of course: If documentation is not part of the DoD, then it surely won’t be done.

\n\n

Remember: arc42 proposes lean, economical and compact documentation that can be incrementally or iteratively enhanced.

\n\n

Question E-3: How can arc42 help us in reducing documentation effort?

\n\n

Document crosscutting concepts instead of too many building blocks.
Use abstractions in the building block view and runtime view.

\n\n

Question E-4: We use Scrum. How can we integrate arc42 into our sprints?

\n\n

Documentation shall be part of your Definition-of-Done. Therefore arc42 is automatically included in Scrum processes.

\n\n

Question E-5: In agile projects, what kind of information shall we write down and what shall we communicate orally?

\n\n

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…

\n\n

Question E-6: In agile projects, can we skip (defer) documentation for a while and focus only on implementing?

\n\n

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.

\n\n

We urge you - document economically (short, brief, compact), but do this continously.

\n\n

Question E-7: What are the most important tips for documentation in agile projects?

\n\n

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:\n
1. care for the adequate form and content and
2. proactively search for unnecessary or outdated parts and remove them.\nPlease 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.
\n
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.

\n\n\n\n\n

F Questions on tools for arc42

\n\n\n\n

As authors, we reserve the right to explain our personal experience and opinion. You should\nnot base your tool selection solely on the information given here! There might be awesome tools\navailable which we failed to mention…

\n\n

Question F-1: What tools are well-suited for arc42?

\n\n

This is a classical it depends type of question. Ask three different people, get at least five different (and most likely conflicting) answers…

\n\n

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

\n\n

Question F-2: What are useful criteria for selecting a toolset for arc42?

\n\n

Some other criteria to watch out for:

\n\n

Teamwork: several people should be able to work in parallel
Versioning: documentation artifacts need to be version-controlled. That’s quite easy\nfor 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).\nSome tools excel in this, others fail miserably.
Robustness: You don’t want to re-create diagrams or documentation because your boss made\nyou use that (supposedly) cheap free-and-open-source documentation tool… I had especially\nbad 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,\nalso in methodical questions.

\n\n

Question F-3: Can I automatically include important code artifacts in arc42 documentation?

\n\n

Short answer: Never (!) copy/paste code into your documentation - as it will be outdated before you hit the save key.

\n\n

Longer answer (for AsciiDoc):

\n\n

You can include code fragments be the following scheme:

\n\n

1 [source,groovy]\n2 ----\n3 include::{sourcedir}/Sample.groovy[lines=1;7..-1]\n4 ----\n

\n\n\n\n

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:

\n\n

1 class Sample {\n2    // tag::helloMethod[]\n3    String hello() {\n4      'Asciidoc rules!'\n5    }\n6    // end::helloMethod[]\n7  }\n

\n\n\n\n

and then reference this snippet in your documentation as follows:

\n\n

1 [source,groovy]\n2 ----\n3 include::Sample.groovy[tags=helloMethod]\n4 ----\n

\n\n\n\n

See also the awesome blogpost from mrhaki and another on partial includes

\n\n

Question F-4: How do I use arc42 with modeling tools?

\n\n

Most modeling tools lack out-of-the-box arc42 support,\nyou have to create your desired arc42 (sub-)structures\nby yourself.

\n\n

arc42 does provide an empty arc42-structured model\nfor Sparx Enterprise Architect(R), although not very\nelaborated.

\n\n

We advice to restrict the use of modeling tools to the\npure graphical part of architecture documentation,\nleave text and tables to other tools that are more\nsuited for these kinds of information.\nIn this case, create the following arc42-sections in\nyour modeling tool:

\n\n

Context view
Building block view
Runtime view
Deployment view
Crosscutting concepts

\n\n

Question F-5: How can I use arc42 together with Sparx Enterprise Architect(r)\n

\n\n

<t.b.d.>

\n\n

Question F-6: Are there (free or open-source) modeling tools available?

\n\n

Short answer: In principal, yes. For example:\n* UMLet\n* Modelio\n* Violet\n
Longer answer: We have, at least until November 2016, not gotten to know\nany free modeling tool that can really compete with commercial\ntools with respect to robustness, useability, feature completeness and availability-of-know-how.\nBefore you go for any free modeling tool,\nplease make reasonably sure that your candidate fulfills\nthe basic requirements we explained in Question F-2,\nconcerning teamwork, robustness, versioning and artifact generation.\n
Actually, compliance to any specific UML standard is very\noften overrated.
\n

\n\n

Question F-7: Can we use arc42 with the Atlassian Confluence wiki?

\n\n

Yes - it’s a (near-perfect) combination: Confluence³ is a powerful, yet easy-to-use\ncollaboration platform, a “wiki-on-steroids”.

\n\n

You can easyli map the arc42 structure on Confluence pages, and even use\npredefined templates to setup the complete arc42 structure in a breath\n(see question F-8 (Confuence tools) for details on available tooling).

\n\n\n\n

In Confluence, you can tag (label, mark) pages, so it becomes very simple to add\narbitrary meta-information to certain parts of your documentation. Use this e.g. to\nadd version/release-specific information, or to distinguish between “already-implemented”\nand “planned-for-the-future” information.

\n\n

Confluence does not (!) provide out-of-the-box diagramming features, but numerous\ntools are available to the rescue, see question F-9 (Confluence Diagramming tools) for details).

\n\n

Question F-8: What tools can I use to setup arc42 in Confluence?

\n\n

There a a few options to simplify the setup of the arc42 structure within your Confluence:

\n\n

The Networked-Assets ATC macro to insert the arc42 template into any Confluence space.
The smartics Blueprints for arc42\n
(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.

\n\n

See question F-9 (Diagrams in Confluence) for an overview of diagramming tools available for Confluence.

\n\n

Question F-9: How can I create diagrams in Confluence?

\n\n

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:\n
- \nGliffy, 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.
- \nDraw.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.
\n

\n\n

Question F-10: What tools shall I use for sequence diagrams?

\n\n

Sequence diagrams (SDs) can be really useful to document or specify runtime scenarios,\nsee question C-6-3 (how to document scenarios), but they are time-consuming to create and maintain with graphical modeling tools.

\n\n

We will briefly discuss the following options:

\n\n

UML tools for SDs
\nSDs generated by PlantUML from textual description
SDs with browser apps

\n\n

UML tool for sequence diagrams

\n\n

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.

\n\n

Sequence diagrams generated from textual description

\n\n

PlantUML is a free tool that can render sequence diagrams from a textual description.

\n\n

Consider an example: In the following listing you find the description of a simple sequence, shown in the figure below:

\n\n

1 @startuml\n2 G -> G : init\n3 G -> H : sendEmail()\n4 G <--H : reply X\n5 G -> I : blabla( X )\n6 I -> H : check( X )\n7 I <--H : ok\n8 @enduml\n

\n\n\n\n\n

\"PlantUML — PlantUML sequence diagram example

\n\n\n

Charming: Such textual descriptions can be merged and versioned like any other source code!

\n\n

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.

\n\n\n\n

SDs build with browser apps

\n\n

You may have a look at:

\n\n

\nDrawIO, an interactive (browser-based) graphic editor that can draw arbitrary (vector) graphics. Quite cool is the offline feature.
\nWeb-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:

\n\n

1 title Authentication Sequence\n2 Alice->Bob: Authentication Request\n3 note right of Bob: Bob thinks about it\n4 Bob->Alice: Authentication Response\n

\n\n\n\n\n

\"WebSequenceDiagram — WebSequenceDiagram example

\n\n\n

Question F-10: Can I use PlantUML for building block / component diagrams?

\n\n

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.\nThat’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.\n

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.

\n\n

From my experience, static diagrams, like class- or component diagrams, look well only in hello-world like situations…

\n\n\n\n\n

G Questions on arc42 and versions / variants

\n\n

Question G-1: Shall I version control our architecture documentation?

\n\n

Yes, of course!. At best with the same strategy, processes and tools you use for your source code.

\n\n

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

\n\n

If you cannot use your version control system for your\n(architecture) documentation, see Question G-2.

\n\n

Question G-2: We cannot use version control for documents. What to do?

\n\n

Really (really!) make sure you find a (mostly automated)\nway to get your documentation under version control.

\n\n

One way which helped me several times is the following:

\n\n

When you release your software (in continous deployment\nscenarios, you might stick to major releases…),\ncreate a pdf file from your documentation.
Put this pdf under version control, in the same branch,\ntag/label or release info as your code-to-be-released.

\n\n

Question G-3: How does versioning work with graphical models?

\n\n

Although some tool vendors argue differently, recognizing the meaning\nof differences in diagrams imho requires human intelligence:\nI (Gernot) have not yet found any automatism supporting meaningful diff\nof diagrams or images. In my opinion somebody needs to care for\nnew versions of diagrams.

\n\n

It’s often a good idea to (automatically) include the modification date\nin a diagram (some modeling tools support this feature).

\n\n

Question G-4: How can I describe several variants of a system?

\n\n

<t.b.d.>

\n\n\n\n\n

H Questions on arc42 and traceability

\n\n

Question H-1: What does traceability mean (with arc42)?

\n\n

“Traceability (or Requirements Traceability) refers to the ability to link product requirements back to stakeholders’ rationales and forward to corresponding design artifacts, code, and test cases.” (quoted from Wikipedia)

\n\n

Full-scale traceability needs every single requirement\nto be referenced in any part of the architecture/solution\ndocumentation.

\n\n

From a more pragmatical architectural (arc42) perspective,\ntraceability can also refer\nto the understandability or explanation of important or fundamental architecture or\nsolution decisions: “We took the decision Dec-X because of\nthe requirements Req-Y.”

\n\n

Question H-2: Shall we strive for traceability in our documentation?

\n\n

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\nmedical, pharmaceutical or avionics, you are most likely required to provide traceability.

\n\n

One nice hook within arc42 are blackboxes within the building block view: Use the blackbox template to document:

\n\n

the requirements fulfilled or satisfied by this particular building block,
the source code needed to implement this building block.

\n\n

Question H-3: How can I keep architecture documentation in sync with source code?

\n\n

We’ve several suggestions, but the most important one first:

\n\n\n\n

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

\n\n\n\n\n

J Questions on managing documentation

\n\n

Question J-1: How to document (very) large systems with arc42

\n\n

Modularize extensive documentation:

\n\n

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

\n\n

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

\n\n

A toolchain supporting modularization is an important prerequisite:\nit’s a nuisance with typical office products, but works quite\nsmoothly with wikis or markup-languages.

\n\n

For a schematic example of modularized documentation see\nfigure 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.

\n\n

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

\n\n\n

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

\n\n

Question J-2: Does a documentation governance make sense for architecture documentation?

\n\n

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.

\n\n

Answer the following questions for your situation. The more “yes” answers the more useful a regulated documentation might be:

\n\n

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

\n\n

Question J-3: Is there a checklist for arc42 documentation?

\n\n

See question J-4.

\n\n

Question J-4: Is there a general checklist for architecture documentation?

\n\n

Counterquestion: What do you want to achieve with such a checklist?

\n\n

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\n(see also question E-2 )

\n\n

Question J-5: How can I create delta-documentation with arc42?

\n\n

In other words: How can I document the changes (deltas) between two consecutive versions of a system?

\n\n

<t.b.d.>

\n\n

Question J-6: What level of access permissions shall stakeholders have on the architecture documentation?

\n\n

Short answer

Keep the administrative effort as low as possible: If you\naccord 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:\n

For large teams, you should modularize your documentation\nand restrict write-access to certain parts, to avoid\naccidental changes.
You might differentiate (short-term) project\nand (long-term) system documentation. Everybody can\nwrite in project documentation, only few people might modify\nsystem documentation.
In case of regulated documentation, you might need\ndetailed permissions (and access logs) to avoid manipulation.

\n\n\n

K Questions on customizing arc42

\n\n

Question K-1: Are we allowed to customize arc42 for our (company/organization/system…) purpose?

\n\n

Yes, of course. See Question A-2 (arc42 License).

\n\n

You may modify the structure of the template, re-create it in any tool of\nyour choice or even rename it for your own purpose\n(one of our clients called it SAT42, what we really enjoyed.)

\n\n

To be fair, you should reference Gernot Starke and Peter Hruschka\nas creators of arc42 in case you use or modify the template…

\n\n

Question K-2: What kinds of customizations are common for arc42?

\n\n

Short answer

Customize or change arc42 only if you absolutely need to. The\nstandardized structure of arc42 has a high recall value - many people are\naccustomed to it.

Longer answer

Keep arc42 modifications to subsections and leave the high-level structure unchanged.\n

I (Gernot) encountered the following modifications during real-world projects:

\n\n

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.

\n\n\n\n\n\n\n\n

arc42 by Example

\n\n

Also published on Leanpub, this collection of real-world systems, documented and explained\nwith the proven and pragmatic arc42 template.

\n\n\n

\n\n\n

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.

\n\n

Communicating Software Architectures

\n\n

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

\n\n\n

\n\n\n

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

\n\n

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\nthis chapter of arc42-in-practice.)

\n\n

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

\n\n

arc42 in Aktion (German)

\n\n

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

\n\n\n

\n\n\n

You get it at your local bookstore or online.

\n\n

iSAQB CPSA-Foundation Study Guide

\n\n\n

\n\n\n

Also published on Leanpub, this book helps you prepare for the iSAQB\nexamination “Certified Professional for Software Architecture - Foundation Level”.

\n\n\n

About Gernot Starke

\n\n\n

\n $\"\"$ \n

\n\n\n\n

Dr. Gernot Starke (innoQ Fellow) is co-founder and\nlongstanding user of the (open source) arc42\ndocumentation template. For more than 20 years he works as software\narchitect, coach and consultant, conquering the challenges of creating effective software architectures for clients from various industries.

\n\n

In 2008 Gernot co-founded the International Software Architecture Qualification Board (iSAQB e.V.) and since then\nsupports it as an active member.

\n\n

2014 he founded the (open source) Architecture Improvement Method aim42.

\n\n

Gernot has authored several (German) books on software architecture and related topics.

\n\n\n

\n $\"\"$ \n

\n\n\n\n

Gernot studied computer science at the Institute of Technology in Aachen\n(RWTH Aachen) and finished with a Diploma. He then worked as a\ndeveloper and consultant for smaller software companies, before coming\nback 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”.

\n\n

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\nlead the first European Java Project (the Janatol project for Hypobank in Munich).

\n\n

Since then he has consulted and coached numerous clients from various\ndomains, mainly finance, insurance, telecommunication, logistics,\nautomotive and industry on topics around software engineering, software\ndevelopment and development process organization.

\n\n

Gernot was an early adopter of the agile movement and has successfully\nworked as Scrum master in agile projects.

\n\n

He lives in Cologne with his wife (Cheffe Uli) and his two (nearly grown-up)\nkids, two cats and a few Macs.

\n\n

Email Gernot Starke\nor contact him via Twitter @gernotstarke.

Notes

1Table generated: November/24/2016↩

\n\n

3The name and logo of Confluence is copyrighted by Atlassian Software. arc42 is neither affiliated with or in any way sponsored by Atlassian Corporation.↩

\n\n\n

\n\n

\n\n","tocStructure",[154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169],{"_72":73,"_38":74,"_66":-5,"_75":76,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":73,"_38":82,"_66":-5,"_75":83,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":73,"_38":86,"_66":-5,"_75":87,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":90,"_38":91,"_66":-5,"_75":92,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":90,"_38":96,"_66":-5,"_75":97,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":90,"_38":99,"_66":-5,"_75":100,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":90,"_38":102,"_66":-5,"_75":103,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":90,"_38":105,"_66":-5,"_75":106,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":90,"_38":108,"_66":-5,"_75":109,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":90,"_38":111,"_66":-5,"_75":112,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":90,"_38":114,"_66":-5,"_75":115,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":90,"_38":117,"_66":-5,"_75":118,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":90,"_38":120,"_66":-5,"_75":121,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":73,"_38":123,"_66":-5,"_75":124,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":73,"_38":127,"_66":-5,"_75":128,"_68":77,"_93":-5,"_94":-5,"_80":-5},{"_72":73,"_38":131,"_66":-5,"_75":132,"_68":77,"_93":-5,"_94":-5,"_80":-5},"publicChapterContent","nextChapter","sections",[],"routes/_store+/_layout","routes/_store+/_readers+/_layout","actionData","errors"]

Notes

Table of Contents

Introduction

Table of Questions

Frequently Asked Questions

A General questions

Question A-1: What does the 42 mean?

Question A-2: What’s the license?

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

Question A-4: How widely is arc42 used?

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

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

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

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

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

B Questions on methodology

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

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

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

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

Question B-5: Where to document external interfaces?

Question B-6: How to document external interfaces?

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

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

Question B-9: What is a whitebox?

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

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

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

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

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

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

Question B-16: What does economical documentation mean?

C Questions on arc42 sections

1. Requirements, quality-goals, stakeholder

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

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

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

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

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

2. Constraints

Question C-2-1: What are constraints?

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

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

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

3. Context

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

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

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

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

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

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

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

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

4. Solution strategy

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

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

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

From the Html-Sanity-Checker example architecture

From a Mass-Market CRM system

5. Building block view

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

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

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

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

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

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

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

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

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

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

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

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

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

6. Runtime view

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

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

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

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

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

7. Deployment view