arc42 Documentation
143 tips and 33 examples how to use the arc42 template.

  • Home
  • 1 - Introduction and Goals
  • 2 - Constraints
  • 3 - Context and scope
  • 4 - Solution strategy
  • 5 - Building block view
  • 6 - Runtime view
  • 7 - Deployment view
  • 8 - Concepts
  • 9 - Architecture decisions
  • 10 - Quality
  • 11 - Risks and technical debt
  • 12 - Glossary
  • All examples
  • All tips (by keyword)
  • Contact

Search Results

Tip 9-10: Use lightweight tooling to support creation of ADRs

  • #decision
  • #adr
  • #tooling

Tip 9-9: Follow the _suggestions for good ADRs_

  • #decision
  • #adr

Tip 9-8: Decisions should have a timestamp!

  • #decision
  • #adr

Tip 1-24: Make use of the (open-source) collection of quality requirements examples!

  • #requirement
  • #quality
  • #scenario
  • #quality-scenario

Tip 5-28: Explain concepts instead of building blocks!

  • #building-block
  • #concept

Tip 5-27: Refine only a few building blocks!

  • #building-block
  • #hierarchy

Tip 5-26: Make the origin of lower-level building blocks explicit!

  • #building-block
  • #hierarchy

Tip 5-25: If useful, refine several building blocks at once!

  • #building-block
  • #hierarchy

Tip 5-24: Use building-block level-1 for **other** information!

  • #building-block

Tip 5-23: Document or specify interfaces with runtime scenarios!

  • #building-block
  • #interface
  • #scenario
  • #runtime-scenario

Tip 5-22: Document or specify interfaces with unit-tests!

  • #building-block
  • #interface
  • #test

Tip 5-21: Describe or specify internal interfaces with minimal effort!

  • #building-block
  • #interface
  • #lean

Tip 5-20: Clearly indicate third-party elements in the building block view!

  • #building-block

Tip 8-10: Use the collection from arc42 as checklist for concepts!

  • #concept
  • #lean

Tip 7-10: Leave hardware decisions to hardware-experts!

  • #deployment-view
  • #lean

Tip 6-11: Use sequence diagrams to describe or specify runtime scenarios!

  • #runtime-view
  • #scenario
  • #sequence-diagram

Tip 6-10: Use both small and large building blocks in scenarios!

  • #runtime-view
  • #scenario
  • #building-block
  • #lean

Tip 5-19: In exceptional cases include third-party software in the building block view!

  • #building-block

Tip 5-18: Ensure **every** piece of source code can be located in the building block view!

  • #building-block
  • #source-code

Tip 5-17: 'Cohesion' shall be the primary driver when creating architecture building blocks!

  • #building-block
  • #source-code
  • #cohesion

Tip 5-16: Map building blocks according to modularization constructs of your programming language!

  • #building-block
  • #source-code
  • #mapping

Tip 5-15: Align the mapping of source-code to building-blocks along the directory and file structure!

  • #building-block
  • #source-code
  • #mapping
  • #lean

Tip 5-14: Explain where to find the source code of your building blocks!

  • #building-block
  • #source-code
  • #mapping

Tip 5-13: Explain the mapping of source-code to building blocks!

  • #building-block
  • #source-code
  • #essential
  • #mapping

Tip 5-12: Refine building-blocks consistently!

  • #building-block
  • #hierarchy

Tip 5-11: Show multiple levels of the building block view!

  • #building-block
  • #hierarchy

Tip 5-10: Use crosscutting concepts to describe or specify similarities in building blocks!

  • #building-block
  • #concept
  • #lean

Tip 3-19: Defer technical context to the deployment view!

  • #context
  • #technical-context
  • #deployment-view
  • #lean

Tip 3-18: Explain the relationship between domain interfaces and their technical realization!

  • #context
  • #interface

Tip 3-17: Combine business context with technical information!

  • #context
  • #technical-context
  • #business-context
  • #infrastructure
  • #lean

Tip 3-16: Use the technical context to describe protocols or channels!

  • #context
  • #thorough
  • #technical-context

Tip 3-15: Show the technical context (in case hardware is central to your system)!

  • #context
  • #technical-context

Tip 3-14: Pay attention to quality requirements at external interfaces!

  • #context
  • #quality-goal
  • #external-interface

Tip 3-13: Show transitive dependencies in the context!

  • #context

Tip 3-12: Show external influences in the context!

  • #context

Tip 3-11: In the business context, show data flows (instead of dependencies)!

  • #context
  • #business-context

Tip 3-10: Differentiate business and technical context!

  • #context
  • #technical-context
  • #business-context

Tip 1-23: Classify your stakeholders by interest and influence!

  • #stakeholder
  • #lean

Tip 1-22: Skip the stakeholder table if your management already maintains it!

  • #requirement
  • #stakeholder
  • #lean

Tip 1-21: Maintain a stakeholder table!

  • #stakeholder
  • #essential
  • #thorough

Tip 1-20: Describe the expectations of stakeholders!

  • #requirement
  • #stakeholder
  • #essential

Tip 1-19: Search broadly for stakeholders!

  • #requirement
  • #stakeholder
  • #essential

Tip 1-18: Defer detailed and complete quality requirements to arc42 section 10!

  • #requirement
  • #quality-goal
  • #thorough

Tip 1-17: Combine quality goals with the action points of the 'solutions strategy' section!

  • #requirement
  • #solution-strategy
  • #quality

Tip 1-16: Describe only the top 3-5 quality goals in the introduction!

  • #requirement
  • #quality
  • #scenario
  • #lean
  • #quality-goal

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

  • #requirement
  • #quality
  • #scenario
  • #example

Tip 1-14: Use checklists for quality requirements!

  • #requirement
  • #quality
  • #quality-tree
  • #iso-25010
  • #thorough

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

  • #requirement
  • #quality
  • #assumption
  • #essential

Tip 1-12: Explain quality requirements through scenarios!

  • #requirement
  • #quality
  • #scenario
  • #essential

Tip 1-11: Always work with explicit quality requirements!

  • #requirement
  • #quality
  • #essential

Tip 1-10: Use 'exemplary business process models' to describe functional requirements!

  • #requirement
  • #functional-requirement

Tip 12-6: Make your 'product owner' or 'project manager' responsible for the glossary

  • #glossary
  • #lean

Tip 12-5: Keep the glossary compact! Avoid trivia.

  • #glossary
  • #lean

Tip 12-4: Include translations in the glossary!

  • #glossary
  • #i18n
  • #translation
  • #thorough

Tip 12-3: Amend the glossary by a (graphical) model!

  • #glossary

Tip 12-2: Document the glossary as a table!

  • #glossary
  • #lean

Tip 12-1: Take the glossary seriously!

  • #glossary
  • #essential

Tip 11-6: Analyze source-code for problems and risks!

  • #risk
  • #problem
  • #source-code

Tip 11-5: Analyze data or data structures for problems and risks!

  • #risk
  • #problem

Tip 11-4: Analyze _processes_ for problems and risks!

  • #risk
  • #problem

Tip 11-3: Identify problems or risks by qualitative evaluation!

  • #risk
  • #technical-debt
  • #problem
  • #atam

Tip 11-2: Analyze (external) interfaces for problems and risks!

  • #risk
  • #problem
  • #external-interface
  • #interface

Tip 11-1: Search for problems and risks with different stakeholders!

  • #risk
  • #stakeholder
  • #problem

Tip 10-8: Use (quality) scenarios for architecture analysis or evaluation!

  • #quality
  • #quality-scenario
  • #scenario
  • #atam

Tip 10-7: Consider fault/error/failure (quality) scenarios!!

  • #quality
  • #quality-scenario
  • #scenario

Tip 10-6: Consider change (quality) scenarios!!

  • #quality
  • #quality-scenario
  • #scenario

Tip 10-5: Consider usage or application (quality) scenarios!

  • #quality
  • #quality-scenario
  • #scenario

Tip 10-4: Use the quality tree as checklist!

  • #quality-tree
  • #thorough
  • #iso-25010

Tip 10-3: Use a mind-map as quality tree!

  • #quality
  • #quality-tree

Tip 10-2: Document and explain the specific quality tree!

  • #quality
  • #quality-tree

Tip 10-1: Keep the quality goals in arc42-section 1.2 short!

  • #quality
  • #quality-scenario
  • #quality-goal

Tip 9-7: Document decisions informally as a blog (RSS-feed)!

  • #decision
  • #lean

Tip 9-6: Document rejected alternatives!

  • #decision
  • #thorough

Tip 9-5: Document decisions as `Architecture Decision Record` (ADR)!

  • #decision

Tip 9-4: Document decisions as mind-map or as table!

  • #decision
  • #quality
  • #stakeholder

Tip 9-3: Provide reasons for important decisions!

  • #decision
  • #essential

Tip 9-2: Document decision criteria!

  • #decision
  • #criteria
  • #stakeholder
  • #essential

Tip 9-1: Document only architecturally relevant decisions!

  • #decision
  • #quality
  • #stakeholder
  • #lean

Tip 8-9: Document decisions instead of concepts!

  • #concept
  • #lean

Tip 8-8: Document concepts with source code!

  • #concept
  • #source-code
  • #example
  • #test

Tip 8-7: Document (at least) the (business or domain) data model!

  • #concept
  • #domain
  • #essential
  • #plantUML

Tip 8-6: Combine business or domain models with the glossary!

  • #concept
  • #domain
  • #glossary

Tip 8-5: Document business or domain models!

  • #concept
  • #domain

Tip 8-4: In concepts, explain HOW it works!

  • #concept
  • #source-code
  • #example

Tip 8-3: Restrict documentation of concepts to the most important topics!

  • #concept

Tip 8-2: Concepts are approaches, rules, principles, tactics, strategies etc...

  • #concept

Tip 8-1: Explain the Concepts!

  • #concept
  • #lean
  • #essential

Tip 7-9: Explain what (else) is relevant for productive use (aka operation) of the system!

  • #deployment-view

Tip 7-8: Explain your nodes!

  • #deployment-view
  • #hardware

Tip 7-7: Use tables to document software/hardware mapping!!

  • #deployment-view
  • #lean

Tip 7-6: Use UML deployment diagrams to document software/hardware mapping!

  • #deployment-view
  • #mapping

Tip 7-5: Document the mapping of building-blocks to hardware!

  • #deployment-view
  • #mapping

Tip 7-4: Document the deployment view hierarchically!

  • #deployment-view
  • #hierarchy

Tip 7-3: Document the various environments!

  • #deployment-view

Tip 7-2: Explain hardware and infrastructure decisions!

  • #deployment-view
  • #hardware
  • #decision

Tip 7-1: Document your technical infrastructure (hardware)!

  • #deployment-view
  • #hardware
  • #infrastructure

Tip 6-9: Use a textual notation to describe runtime scenarios!

  • #runtime-view
  • #scenario
  • #lean

Tip 6-8: Use activity diagrams with partitions to describe or specify runtime scenarios!

  • #runtime-view
  • #scenario
  • #activity-diagram

Tip 6-7: Use activity diagrams with swimlanes to describe or specify runtime scenarios!

  • #runtime-view
  • #scenario
  • #activity-diagram

Tip 6-6: Describe excerpts of scenarios (partial scenarios)!

  • #runtime-view
  • #scenario
  • #sequence-diagram

Tip 6-5: Use scenarios primarily to `discover` building blocks, not so much for documentation!

  • #runtime-view
  • #scenario

Tip 6-4: Document detailed scenarios (with caution)!

  • #scenario
  • #runtime-view
  • #thorough
  • #runtime-scenario

Tip 6-3: Document 'schematic' (instead of detailed) scenarios!

  • #scenario
  • #runtime-view
  • #lean
  • #runtime-scenario

Tip 6-2: Document only a few runtime scenarios!

  • #scenario
  • #runtime-view
  • #lean
  • #essential
  • #runtime-scenario

Tip 6-1: Always map existing building blocks to the activities within runtime scenarios!

  • #scenario
  • #runtime-view
  • #essential
  • #runtime-scenario

Tip 5-9: Use runtime views to explain or specify whiteboxes!

  • #building-block
  • #whitebox
  • #runtime-view

Tip 5-8: Justify every whitebox structure!

  • #building-block
  • #whitebox

Tip 5-7: Use tables to efficiently document/specify blackboxes!

  • #building-block
  • #table
  • #blackbox

Tip 5-6: Hide the inner workings of blackboxes!

  • #building-block
  • #blackbox
  • #lean
  • #essential

Tip 5-5: Describe the responsibility or purpose of every (important) blackbox!

  • #building-block
  • #blackbox
  • #essential

Tip 5-4: Ensure consistency of external interfaces to level-1

  • #building-block
  • #external-interface
  • #whitebox

Tip 5-3: Always describe level-1 of the building block view ('Level-1 is your friend')!

  • #building-block
  • #hierarchy
  • #essential
  • #lean

Tip 5-2: Organize the building block view hierarchically!

  • #building-block
  • #hierarchy
  • #source-code
  • #essential

Tip 5-1: Use common structures for sections of the building block view!

  • #building-block
  • #blackbox
  • #whitebox

Tip 4-6: Justify the solution strategy!

  • #solution-strategy

Tip 4-5: Let the solution strategy grow iteratively / incrementally!

  • #solution-strategy
  • #lean

Tip 4-4: In the solution strategy, refer to concepts, views or code!

  • #solution-strategy
  • #concept
  • #view
  • #source-code

Tip 4-3: Describe solution approaches in context of quality requirements!

  • #solution-strategy
  • #quality
  • #quality-scenario

Tip 4-2: Describe the solution approaches as a table!

  • #solution-strategy
  • #table
  • #concept
  • #scenario
  • #quality-goal
  • #lean
  • #essential

Tip 4-1: Explain the solution strategy as compact as possible (e.g. as list of keywords)!

  • #solution-strategy
  • #concept
  • #lean

Tip 3-9: Show all (all!) external interfaces!

  • #context
  • #external-interface
  • #essential

Tip 3-8: Aggregate (cluster) similar neighbour systems with ports!

  • #context
  • #port

Tip 3-7: If many external systems are involved, aggregate (cluster) them by explicit criteria!

  • #context
  • #cluster
  • #criteria

Tip 3-6: Simplify the context by categorization!

  • #context
  • #external-interface
  • #lean

Tip 3-5: Restrict the context to an overview, avoid too many details!

  • #context
  • #essential
  • #lean

Tip 3-4: Explicitly indicate risks in the context!

  • #context
  • #risk

Tip 3-3: Combine the context diagram with a table!

  • #context
  • #essential

Tip 3-2: Show the context as diagram!

  • #context
  • #external-interface
  • #essential

Tip 3-1: Explicitly demarcate your system from its environment!

  • #context
  • #external-interface

Tip 2-5: Differentiate different categories of constraints!

  • #constraint
  • #essential

Tip 2-4: Document design and development constraints!

  • #constraint

Tip 2-3: Document organizational constraints!

  • #constraint

Tip 2-2: Clarify the consequences of constraints!

  • #constraint
  • #stakeholder

Tip 2-1: Consider the constraints of other systems within the organization!

  • #constraint

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

  • #requirement
  • #plantUML
  • #activity-diagram
  • #functional-requirement

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

  • #requirement
  • #functional-requirement

Tip 1-7: Use BPMN diagrams to describe functional requirements!

  • #requirement
  • #bpmn
  • #functional-requirement

Tip 1-6: Use activity diagrams to describe functional requirements!

  • #requirement
  • #activity-diagram
  • #functional-requirement

Tip 1-5: Make sure you can reference (existing) requirements!

  • #requirement
  • #thorough

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

  • #requirement
  • #cluster
  • #functional-requirement

Tip 1-3: Highlight the business goals of the system!

  • #requirement
  • #goal

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

  • #requirement

Tip 1-1: Give a compact summary of requirements and driving forces!

  • #requirement

arc42 offers architecture training.

Two expert trainers at all times, highly practical and pragmatic, ideal preparation for iSAQB CPSA-Foundation certification. Depending on the COVID-19 situation, some workshops might be conducted online.
Next available dates (in German):
  • June 28-July 1st 2022, Frankfurt
  • Sept 13-16th 2022, Frankfurt
  • Nov 29th - December 2nd 2022, Munich

iSAQB Advanced Topics

IMPROVE: Learn to effectively evolve and maintain systems.
  • Nov 22.-24. 2022, Hamburg (Carola Lilienthal with Gernot Starke)
Req4Arc: Getting your Requirements right.
What to do if your requirements need improvement.
  • Sept 21.-23 2022, Frankfurt (Peter Hruschka with Gernot Starke)
ADOC: Architecture Documentation
How to efficiently and effectively create and maintain useful technical documentation.
  • Sept 19.-20th 2022, Frankfurt (Gernot Starke and Peter Hruschka)

Early bird rates available. Contact us for inhouse training.
Imprint + Privacy Statement
Maintained by Gernot Starke with Peter Hruschka, supported by INNOQ