After my "The Art of Simple Software Architecture Documentation" talk, a surprising number of people asked for the slides because they saw the deck as a reference guide. This post is the starting point: why arc42 works so well, how I approach it in practice, and what each of the 12 chapters looks like when you fill them in for real.

Chapter 1 sets the direction for the entire architecture document. If you do not know why you are building this and who it is for, you cannot design it properly. In this article I show what belongs in chapter 1, what to keep out, and a minimal structure you can copy, plus a small example from Pitstop.

Chapter 2 lists the non-negotiables that shape your design space. If you do not write these down early, they will still exist, but they will surprise you later. In this article I show what belongs in chapter 2, what to keep out, and a minimal structure you can copy, plus a small example from Pitstop.

Chapter 3 draws the boundary of your system. If it is unclear what is inside and outside, integrations and expectations will break first. In this article I show what belongs in chapter 3, what to keep out, and a minimal structure you can copy, plus a small example from Pitstop.

Chapter 4 opens the "How is it built and how does it run" group. It is where goals, constraints, and context from the first three chapters start to shape the design through a small set of guiding decisions. In this article I show what belongs in chapter 4, what to keep out, how to handle open strategy questions, and a flexible structure you can copy, plus a small example from Pitstop.

Chapter 5 turns strategy into structure using white-box decomposition. It describes the static building blocks of your system, their responsibilities, and the most important dependencies, without diving into runtime flows. Learn what belongs in chapter 5, what to keep out, and get a copy/paste template plus a real example from Pitstop.

Chapter 6 describes runtime behavior: how building blocks collaborate in the scenarios that matter, including alternatives, exceptions, and the bits that tend to hurt in production. It is also the third chapter in the "How is it built and how does it run" group. In this article I show what belongs in chapter 6, what to keep out, a flexible structure you can copy, plus a small example from Pitstop.

This post is about chapter 7: Deployment view, the last chapter in the "How is it built and how does it run" group. Chapter 7 answers: where do your building blocks run, in which environments, and with which settings? This chapter turns "it works on my machine" from tribal knowledge into shared documentation. No more guessing which settings matter or where things actually run.

Chapter 8 is the patterns and practices chapter. It captures the reusable concepts that keep your domain code lean and your runtime scenarios readable: security, resilience, observability, integration rules, and other "plumbing" that should be consistent. In this article I explain what belongs in chapter 8, what to keep out, a minimal structure you can copy, plus a small example from Pitstop.

Chapter 9 is your decision timeline. It records the important architectural choices you made along the way, so you can see what was decided, why, and which options were not picked. This chapter often starts small, but it grows as the system grows. In this article I explain what belongs in chapter 9, what to keep out, a minimal structure you can copy, plus a small example from Pitstop.

Chapter 10 turns quality goals into testable quality scenarios. It helps you move beyond vague words like "fast" or "secure" by describing concrete situations, expected responses, and measurable targets. ISO/IEC 25010 and Q42 can help as a structure and inspiration, but the real value is iteration: refine goals, learn from reality, and tighten scenarios over time. In this article I explain what belongs in chapter 10, what to keep out, a minimal structure you can copy, plus a small example from Pitstop.

Chapter 11 keeps uncomfortable truths visible. It records the risks and technical debt that can still bite you later, so they do not stay hidden in someone's head or scattered across chat logs. In this article I explain what belongs in chapter 11, what to keep out, a minimal structure you can copy, plus a small example from Pitstop.

Chapter 12 builds shared language. It explains the terms, abbreviations, and domain concepts used throughout the architecture document, so readers do not have to guess what words mean or how the team uses them. In this article I explain what belongs in chapter 12, what to keep out, a minimal structure you can copy, plus a small example from Pitstop.

The arc42 template is a great structure, but structure alone does not keep documentation alive. In my talk I end with the practical part: where to store the docs, how to review them, how to avoid drift, and how to use agents as guardrails. This post captures those "after the template" slides in a form you can actually use.