https://www.innoq.com/en/blog/brief-introduction-to-arc42/ INNOQ [ ] [ ] Contact DE | CH | EN Menu * Services [ ] expanded collapsed + Strategy and Technology Consulting + Digital Product Development + Software Architecture and Development + Digital Platforms and Infrastructures + Knowledge Transfer, Coaching and Trainings * Success Stories * Culture [ ] expanded collapsed + How we collaborate + What's important to us + Working at INNOQ * Magazine [ ] expanded collapsed + Blog & Articles + Podcasts + Talks + Technology Lunch + Primers + Newsletter + Media Art * Trends [ ] expanded collapsed + Accessibility + Cloud Migration + Data Mesh + MLOps + Self-contained Systems + Service Mesh * Trainings [ ] expanded collapsed + Why Online Trainings? + iSAQB CPSA-F Foundation Level + Accessibility + Blockchain + Cloud Native Infrastructure + Cloud Migration + Domain-driven Design + DDD for Machine Learning + Flexible Architectures + JavaScript + Modernization + Product Ownership + Remote Mob Programming + Software Analytics + Web Architecture + Web Security Main menu Blog Post Documenting software architecture with arc42 A brief introduction August 04, 2022 arc42 is a template for architecture communication and documentation. It is a proven, practical and highly pragmatic approach and takes the pain out of documentation. 9 minutes reading time Avatar of Gernot Starke Gernot Starke content 1. Before we dive in... 2. The structure of arc42 3. Like what you saw? 4. Comments or questions? arc42 [1] provides everything you ever need to communicate and document your software architecture. It's tool and technology agnostic, therefore you can use arc42 for arbitrary systems. arc42 is open source and completely free to use. This article provides a quick overview of arc42 and its parts. For more information, please consult the (rather extensive) documentation [2] available on their documentation website (which, since V8/January 2022, contains several practical examples). arc42 answers the following two questions in a pragmatic way and can be tailored to your specific needs: * What should you document/communicate about your architecture? * How should you document/communicate? If you work under time or resource constraints, you will most likely skip certain parts of arc42. Our upcoming post on "lean documentation" will give guidance for such cases. Before we dive in... * Everything is optional - there is no need to fill in every section of the template. Treat arc42 documentation like the compartments of a cabinet, similar to the image below: The cabinet has a value, even if certain compartments remain empty. * The order of these compartments is optimized for reading and understandability. You create your content in any order you like or your project requires. For example, in many development projects, the context (section 3) is defined and created first, followed by the top quality requirements (section 1.2). * arc42 is completely tool agnostic. You might create and maintain arc42 in your tool chain of choice: A wiki, a collection of Office documents, plain Markdown or Asciidoc, one of the commercial UML tools or even LaTeX. Whatever your tool of choice is, arc42 has you covered. The structure of arc42 arc42 proposes a dozen sections (aka compartments) for your documentation. These are organized top-down to improve understandability. arc42 overwiew 1. Introduction and goals Short description of the requirements and driving forces of your system: You should provide an extract or abstract of requirements. Restrict yourself to the top three (max five) quality requirements for the architecture, which have the highest priority for the major stakeholders. Include a table of important stakeholders with their expectation regarding architecture or documentation. intro and goals overwiew 2. Constraints Anything that constrains teams in design and implementation decisions, or decision about related processes. Constraints can sometimes go beyond individual systems and might valid for whole organizations and companies (e.g. company-wide technology choices or government regulations). Time and money are common constraints in many organizations. constraints overwiew 3. Context and scope The context delimits your system from its (external) communication partners (neighboring systems and users). It specifies or documents the external interfaces. You should always document the context from a business or domain perspective. If infrastructure or specific hardware plays an important role, you might also show a technical perspective. context overwiew 4. Solution strategy Summary of the fundamental decisions and solution strategies that shape the architecture: can include technology, top-level decomposition, approaches to achieve top quality goals and relevant organizational decisions. 5. Building block view Usually, boxes and arrows, showing the high-level code structure of the system. To phrase it a little more formal: The building block view explains the static structure of the system and contains, abstractions of source-code. It refines the context view, where the complete system is depicted as a black box. building block overview * Level 1 contains the major subsystems, components or parts of the system. In some cases, this coarse overview provides enough structural overview. * Level 2 refines one or more elements from level 1: Create a separate white box (plus explanations) for every level-1 building block you would like to explain in detail. You can drill down to an arbitrary level of detail, but keep in mind the following: Recommendation Try to stick to level-1, as it often gives enough guidance and understanding for most stakeholders. 6. Runtime view The runtime view explains the behavior or processing of one or several building blocks. It serves as companion to the static building block view from section 5 above. The runtime view might explain important use cases or features, interactions at critical external interfaces, error and exception behavior. runtime overview Recommendation Use runtime scenarios primarily during development to validate or design building block structures. They help to identify missing or unnecessary dependencies. Keep only a small number of scenarios in your documentation. 7. Deployment view Software needs hardware to execute on, that's where the deployment view comes into play: It shows the technical infrastructure with environments, computers, processors, networks and network-topologies. In addition, it maps the software building blocks to those infrastructure elements. deployment overview 8. Cross-cutting concepts Overall, principal regulations and solution approaches relevant in multiple parts (- cross-cutting) of the system. Concepts are often related to multiple building blocks. Include different topics like domain models, architecture patterns and -styles, rules for using specific technology and implementation rules. crosscutting concerns 9. Architecture decisions Keep a collection of architecturally significant decisions that are important, expensive, critical, large scale or risky including rationales, that are not recorded elsewhere. Please use your judgement to decide whether an architectural decision should be documented here or whether you better document it locally (e.g. within the building block view or any cross-cutting concept). You may have already captured the most important decisions of your architecture in the solution strategy. Recommendation: Use Architecture Decision Records to capture decisions in a simple, structured yet pragmatic way. 10. Quality requirements Quality requirements, often described as scenarios. You may use a quality tree to provide a high-level overview. The most important quality goals should have been already described in section 1.2. (quality). scenario overview As the definition of quality scenarios is very abstract, let's look at some examples: Topic Scenario Performance System shall perform all checks on a 100MByte file in less than 10 seconds. The temperature range in which the correct Operability functioning of the device is ensured should range from -25 degrees to +85 degrees Maintainability A new additional verification algorithm can be included in less than one day. 11. Risks and technical debt Known technical risks or technical debt. What potential problems exist within or around the system? What does the development team feel miserable about. In case somebody reviewed or audited your system, their findings might be included here. 12. Glossary Important domain and technical terms that stakeholders use when discussing the system. Please include only specific terms - and avoid explaining REST, HTTPS or other words that have common explanations. In addition, the glossary can serve as the translation reference if you work in a multi-language (international) environment. Like what you saw? Give it a try! Document a few of your architecture decisions, sketch your scope and context and explain a few key technical concepts - and you have your first version of your architecture documentation. Download the template in a format you like. Unpack and start documenting. In case you have questions or want to see examples, consult the extensive documentation site [2]. In case you want to know more, we have you covered: * I wrote about the principles of technical documentation. That deep-dive article explains the fundamental requirements, your technical documentation needs to fulfill - and many proven approaches how to achieve these. * Another article on lean documentation is in the making, please stay tuned. Until then, watch the video "Sparsame Dokumentation" (oops, sorry, it's in German) Comments or questions? Leave a comment right below - or open an issue on the arc42 site. Otherwise, thanx for reading this article. Image of the cabinet by Jan Kolar from Unsplash 1. https://arc42.org. The template has been created by Dr. Peter Hruschka and Dr. Gernot Starke. They published the first version in 2005, after having used predecessor versions for many years in different large and medium-sized projects. - 2. https://docs.arc42.org. The extensive documentation website, containing more than 140 tips and 30 examples on how to use arc42. - TAGS * Software Architecture * Documenting Software Architecture with arc42 Avatar of Gernot Starke Gernot Starke Fellow As an INNOQ fellow, Gernot participates in the strategic development of the company's consulting and implementation products. He supports clients as a consultant for software architecture in general and documentation in particular. Comments Share on * Twitter * Facebook * Mail Recommended Upcoming talks Get in touch Use our contact form or send us an email to [email protected]. You can send us encrypted emails, too. Just use our S/MIME certificates (.cer, .p7b, .pem) or our public PGP key. [ ] Name [ ] Email [ ] [ ] [ ] [ ] [ ] Message [ ] Send Links * Blog & Articles * Talks * Podcasts * Technology Lunch * Primers * Books * Management * socreatory - The Software Creators' Academy * Contact * Privacy * Legal Notice Services * Strategy and Technology Consulting * Digital Product Development * Software Architecture and Development * Digital Platforms and Infrastructures * Knowledge Transfer, Coaching and Trainings Offices innoQ Deutschland GmbH Krischerstr. 100 40789 Monheim am Rhein Tel (+49) 2173 3366 0 Directions Ohlauer Str. 43 10999 Berlin Directions Ludwigstr. 180 E 63067 Offenbach Directions Kreuzstr. 16 80331 Munchen Directions Wendenstrasse 130 20537 Hamburg Directions c/o Design Offices Mediapark Erftstr. 15-17 50672 Koln Directions c/o Design Offices Konigstorgraben 11 90402 Nurnberg Directions innoQ Schweiz GmbH Schutzengelstr. 57 6340 Baar Tel (+41) 41 743 01 11 Directions Hardturmstrasse 253 8005 Zurich Directions Our Newsletters Never miss out on interesting articles, events and podcasts on architecture, development and technology trends! Right now, our newsletters are only available in German. [ ] [ ] Der INNOQ Newsletter Exciting articles, event tips and podcasts on architecture, development and technology trends. Published approx. once per month. (German) I accept the storage and processing of my data in order to receive the monthly newsletter. This acceptance can be revoked via email to [email protected] or by clicking the corresponding links in the newsletter emails. I've read the privacy terms and accept them. [ ] Das Digitale Rauchzeichen Success stories from digitalization and modernization from INNOQ Switzerland. Published up to 4 times per year. (German) I accept the storage and processing of my data in order to receive the monthly newsletter from innoQ Schweiz GmbH. This acceptance can be revoked via email to [email protected] or by clicking the corresponding links in the newsletter emails. I've read the privacy terms and accept them. Email [ ] First name optional [ ] Last name optional [ ] Subscribe Find us on * Twitter * Youtube * LinkedIn * Xing * Feed