The desktop SmartArt gallery in PowerPoint does not show every layout that exists. After some experimentation, I found 23 layouts that are missing from it. Some only surface through Designer suggestions, and a second group only appears in the SmartArt menu of PowerPoint for the web. In this post I catalog all of them, show what each one looks like, and include a downloadable PPTX with copy-and-paste-ready diagrams.

I discovered this by accident. While working with PowerPoint on the desktop, the Designer suggested a diagram style I had never seen in the SmartArt gallery. I went back to Insert > SmartArt to look for it. It simply was not there. That sent me down a rabbit hole of typing different bullet lists and watching what Designer would suggest.

How to access them

1. Open a blank slide in PowerPoint.
2. Type a short bulleted list (3 to 5 items work best).
3. Open the Designer pane from the Home tab or press Design > Designer.
4. Scroll through the suggestions. Some of the proposed layouts are SmartArt diagrams that you will not find in the SmartArt gallery.

Overview

The 23 layouts split into two groups: 15 that are only reachable through Designer, and 8 that also appear in the SmartArt menu of PowerPoint for the web. None of them show up in the desktop SmartArt gallery.

List-style layouts

Process and timeline layouts

Timeline layouts

Designer-only layouts

These 15 layouts do not appear in any SmartArt menu. The only way to get them onto a slide is through a Designer suggestion, on both the desktop and web versions of PowerPoint.

Icon Label List

Each item gets a small icon on the left with a short caption beside it. The layout arranges items horizontally, so it works best with 3 to 5 concise labels. Think feature highlights or a row of team roles.

Icon Circle List

Icons sit inside colored circles with a heading and a short description underneath each one. The circles give the slide a polished, uniform look. A good pick for introducing team members, product pillars, or service categories.

Icon Circle Label List

A variation of the Icon Circle List where the label text is the star of the show. Each circle holds an icon, but the emphasis shifts to the heading text below, with descriptions taking a back seat. Use this when the category names matter more than the details.

Icon Leaf Label List

Icons are placed inside leaf-shaped holders, giving the slide an organic, softer feel compared to circles or rectangles. The layout works well for topics like sustainability, growth stages, or anything that benefits from a less corporate visual style.

Icon Label Description List

Each item has three layers: an icon, a bold heading, and a longer description paragraph. The items are arranged horizontally and give equal space to each entry. Ideal for feature comparisons or explaining three to five concepts that each need a sentence of context.

Centered Icon Label Description List

The same icon-heading-description structure as the previous layout, but everything is center-aligned. This gives the slide a more balanced, symmetrical appearance. Works well for title slides or when the content is short enough that centered text stays readable.

Icon Vertical Solid List

Items are stacked top to bottom, each inside a solid colored bar with an icon on the left and text on the right. The vertical orientation makes it suitable for slides with more items or longer descriptions than the horizontal variants can handle.

Vertical Solid Action List

Full-width solid bars stacked vertically, each holding a heading and description. No icons, no numbering, just bold blocks of color that give every item equal visual weight. A strong choice for agenda slides or listing key takeaways.

Vertical Hollow Action List

The outlined counterpart of the Vertical Solid Action List. Instead of filled bars, each item sits inside a bordered rectangle. The lighter look leaves more breathing room on the slide and works better on slides that already have a colored background.

Basic Process New

A minimal left-to-right process flow. Each step is a colored rectangle connected by arrows, without numbering or extra decoration. Clean enough for a simple three-step workflow or onboarding flow.

Basic Linear Process Numbered

Each step gets a large auto-generated number alongside a heading and description. The steps flow left to right in rectangular blocks connected by arrows. Useful when the sequence order of your steps matters and you want readers to follow 1-2-3.

Linear Block Process Numbered

Similar to the Basic Linear Process Numbered but with thicker, blockier shapes that fill more of the slide. The heavier visual style draws more attention and works well when the process is the main message of the slide.

Linear Arrow Process Numbered

Numbered steps connected by prominent arrows, with text appearing in callout-style shapes that pop out from the flow line. Each step stands out more than in the block variants, making this a good fit for presentations where you walk through each step one at a time.

Vertical Down Arrow Process

Steps flow from top to bottom instead of left to right. Each step is a downward-pointing arrow with the heading inside and a description beside it. Natural for content that involves drilling down, filtering, or funneling.

Chevron Block Process

Chevron-shaped arrows carry the heading text while rectangular blocks above them hold the descriptions. The chevrons create a strong visual flow from left to right. A solid choice for roadmaps or phase-based plans.

Layouts available in the web SmartArt menu

The following 8 layouts do appear in the web app’s SmartArt menu, but only when you use PowerPoint for the web. On the desktop they are still hidden and can only surface through Designer suggestions. If you primarily work in the desktop app, these are just as invisible as the group above.

Repeating Bending Process New

A zigzag flow that bends back and forth across the slide. Instead of running off the right edge, steps wrap to the next row. Well suited for longer processes with six or more steps that need to fit on a single slide.

Basic Timeline

A horizontal timeline line with rounded rectangles for event descriptions and dates placed below. Straightforward and easy to read, good for project milestones or a brief history overview with up to five or six events.

Horizontal Path Timeline

Events sit in rectangles connected by a dotted path with circular markers at each stop. The path gives it a journey or roadmap feel, making it a natural fit for product release timelines or travel itineraries.

Horizontal Labels Timeline

Dates and labels sit directly above or below a horizontal line, without separate description boxes. The compact design keeps the slide clean and works best when each event only needs a short label, like version numbers or quarter names.

Drop Pin Timeline

Each event is marked with a map-pin shape, giving the timeline a location-themed look. The date appears near the pin head and the description below. A playful option that works well for travel recaps, office openings, or any content with a geographic angle.

Rounded Rectangle Timeline

Dates are the focal point here, displayed inside large rounded rectangles along the timeline. Descriptions sit beside or below them in plain text. Choose this when the dates themselves are the main message, such as deadlines or key decision moments.

Hexagon Timeline

Similar to the Rounded Rectangle Timeline, but dates sit inside hexagonal shapes. The angular geometry gives the slide a more technical, eye-catching look. A good match for engineering milestones or sprint-based planning.

Accent Home Chevron Process

Chevron and home-plate-shaped accents carry the headings, with description boxes placed above them. More decorative than the Chevron Block Process and a good fit when you want a process diagram that also catches the eye in a print-out or PDF export.

Layout URNs for technical reference

Each SmartArt layout is identified internally by a unique URN. If you open a PPTX file in a ZIP editor, you can inspect the uniqueId attribute in the diagram XML to confirm which layout is on a slide. This is useful if you find a new hidden layout and want to verify whether it already appears in the list above.

Grab the PPTX and use these layouts in your own slides

I put together a PowerPoint file that contains every hidden layout listed above, pre-filled with placeholder content. You can download it, open the slide you need, and copy the diagram straight into your own presentation.

Download the PPTX with all hidden SmartArt layouts

Because these diagrams are regular SmartArt once they are on a slide, you can edit the text, change colors, and resize them just like any other SmartArt graphic.

Help me discover more

I am fairly sure I have not found all of them yet. Designer suggestions can vary based on your content, the number of bullet points, and possibly even your region or subscription tier.

If you come across a layout that is not in my list, I would love to hear about it.
Drop me a message and I will add it to this post.

Happy diagramming!

The previous 12 chapter posts in this series walked through the arc42 template, chapter by chapter.

But this is my practical series, so I want to 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.

The awkward truth

Documentation does not die because people do not care. It dies because there is no workflow that keeps it connected to change.

arc42 gives you a solid structure for what to write. Now we need a structure for how it stays current.

A minimal workflow that works

This is the workflow I recommend when you want arc42 to stay alive:

• Start early, use arc42 as a blank canvas, even on an existing system, not as a final report.

• Keep it “minimal but honest”.
  Be concise, but do not document sections in isolation. The chapters in arc42 are connected: a constraint in chapter 2 might shape a decision in chapter 9, which in turn affects a building block in chapter 5. If you only look at one section at a time, you will miss those connections.

• Have a team rule: every change that impacts architecture should have:

  • a documentation update that reflects the current state of the design (e.g. when adding or modifying a feature).
  • an ADR that records why a decision was made (e.g. when choosing a technology, pattern, or trade-off).

  These serve different purposes: the docs describe what is, the ADR explains why. Both should happen on significant changes.

• Publish the docs in a readable form, and link them from the repo README.

• Make the team the owner of the docs. The people who build the product maintain the documentation. If the product moves to an operations team, ownership of the docs transfers with it. Without clear ownership, nobody feels responsible, and the docs drift.

That last step matters more than it sounds. If nobody can find the docs, the docs do not exist.

Pick a home for your docs

You have three common options. None is perfect, so pick the one you will actually maintain.

Option 1: Word or requirements tooling

Examples: Microsoft Word, IBM DOORS, Siemens Polarion, Jama Connect.

This can work well for formal sign-off and audit trails, and in regulated industries these tools are often a contractual requirement.

The trade-off is iteration speed: when changes are frequent and reviews are slow, docs tend to describe the intended design rather than the current implementation. In my experience this can create a disconnect between what the docs say and what the code actually does.

Even in these tools, arc42 can still be used to structure the content, so you do not forget to write down all the important aspects.

Option 2: Wikis

Examples: Confluence, Azure DevOps Wiki.

Wikis are easy to edit and easy to collaborate on.

The trade-off is drift:

• It is harder to review changes properly
• It is easy for the wiki to diverge from the code
• It is hard to enforce a “definition of done”

I find wikis useful when collaborating on designs, but in my experience, old designs are left and never cleaned up. That makes it hard to find the current docs, and easy for them to become outdated.

Option 3: In-repo docs (my default)

Examples: AsciiDoc, Markdown.

Plain text files in the same repo as the code.

You get:

• PR-based review
• Versioning together with the implementation
• Enforceable checks (definition of done, linting, link checks, diagram builds)

A major advantage here is Diagrams as Code. Traditional drawing tools are a frequent reason documentation dies, because binary files are hard to update and hard to diff, or because the source can no longer be accessed or found. By using tools like Mermaid.js, PlantUML, or Structurizr, your diagrams become plain text that renders automatically.

This is my default choice, however, it is not a silver bullet. Accessibility and readability can be an issue, especially for non-technical stakeholders. I prefer to have the CI pipeline publish the docs in a readable form (e.g. HTML or PDF) and link them from the README, to make sure they are easy to read and distribute.

For this, Asciidoctor can render AsciiDoc to HTML or PDF. Doxygen, originally an API documentation tool, can also build full websites from Markdown with interlinking and embedding, which makes it useful for architecture docs too. If you are looking for something built specifically for arc42, docToolchain generates HTML and PDF from AsciiDoc-based arc42 documents and integrates with CI pipelines.

Minimum viable documentation: first week starter pack

If you want something you can start with on Monday, this is the smallest set that already prevents expensive misunderstandings:

• Write the context and the most important goals (chapter 1).
  This is what stakeholders ask about first.
• Write some constraints down (chapter 2).
  Constraints narrow the solution space before design begins.
• Draw your service with its neighboring systems (chapter 3).
  A single diagram prevents I did not know we depend on that conversations.
• Write only the top-level building blocks (chapter 5).
  Enough to show the major parts and their responsibilities.
• Write the most important runtime flow (chapter 6).
  The one flow everyone needs to understand to work on the system.
• Start an empty decision log (chapter 9).
  Even if it is empty, having the placeholder signals that decisions should be recorded.
• Write a few quality scenarios (chapter 10).
  Explicit scenarios make “fast enough” and “secure enough” testable.

Notice that chapters 4 (Solution Strategy), 7 (Deployment View), 8 (Cross-cutting Concepts), 11 (Risks), and 12 (Glossary) are not on this list. They are valuable, but you can add them once the core is in place. Chapter 4 often emerges naturally from the decisions you record in chapter 9.

Then iterate. You will discover missing pieces because the structure nudges you into the gaps.

Greenfield vs. brownfield

This starter pack works for both new and existing systems, but the starting point is different.

On a greenfield project, you are filling in a blank canvas: start with goals and constraints, then design from there.

On a brownfield project, the system already exists, and the knowledge is often in people’s heads, not in a document. Start by interviewing the team: ask what the system does (chapter 1), draw the context together (chapter 3), and document the existing building blocks (chapter 5). You will find that writing things down surfaces assumptions and disagreements that were invisible before.

Agents as guardrails

LLMs are good at reading natural language, and they tend to follow explicit rules consistently when those rules are part of the prompt context.

If you use agents (Copilot, Claude, Codex CLI, etc.), add a small instruction file in your repo that makes your arc42 document a source of truth.

Example AGENTS.md:

# Architecture guardrails

Before you propose or implement changes:

- Read the arc42 documentation in `docs/arc42/`.
- Treat it as the source of truth for constraints, decisions, and concepts.
- If a request conflicts with the docs, do not "pick a side".
  Explain the conflict and propose a change to the docs (ADR), the code, or both.

This is not about replacing humans. It is about forcing inconsistencies to surface early.

That said, agents do not always verify what they claim. An LLM might report that it checked the docs without actually reading them, or follow some rules and quietly ignore others. Always verify that the output matches the documented constraints, especially for critical decisions.

Keeping it alive: reviews and drift

A workflow is only as good as the review habit behind it. Without a review cadence, docs drift silently until someone finds a lie in chapter 5 during an incident.

A lightweight approach that works:

• On every PR that touches architecture: update the relevant arc42 sections as part of the definition of done. A concrete DoD entry could be: “arc42 docs reviewed and updated for any architectural impact”.
• After every significant decision: add or update an ADR in the decision log (chapter 9).
• Quarterly (or after a major release): do a full read-through of chapters 1–4 with the team. Are the goals still correct? Have constraints changed? Is the context diagram still accurate?
• Annually: review the full document. Update the glossary, and check that the deployment view matches reality.

The goal is not perfection. It is making drift visible before it becomes expensive.

Wrap-up

The template is only half the game. The other half is having a workflow that makes updates cheap, reviewable, and hard to forget.

If you arrived here directly, the full series walks through every chapter with copy/paste structures, examples, and checklists. The Pitstop example that runs through the series is available as a GitHub Gist.

The arc42 website and its documentation are the best starting points when you want to dive deeper. The FAQ covers common questions, the Quality Model (Q42) helps with quality scenarios, and the Software architecture canvas is a great tool for workshops.

Make some lovely documentation!

This post is about chapter 12: Glossary, the last chapter in the “Reality and shared language” group, and the final chapter of the arc42 template.

A glossary can be a simple list of abbreviations. That is useful, but it is not the main point. The real value is shared meaning: domain terms, recurring concepts, and words that teams use differently. If you practice Domain-Driven Design (DDD), this is where you document your Ubiquitous Language. If you do not use DDD, think of it as the vocabulary the whole team agrees on.

If readers have to ask “what do you mean by that?” while reading the document, the answer should probably live here.

The stakeholders you identified in chapter 1 are your target audience. Their vocabulary and assumptions should drive which terms you define.

What belongs in chapter 12 (and what does not)

Chapter 12 of an arc42 document answers:

Which terms do readers need to understand this document without guessing?

What belongs here:

• Domain terms that show up throughout the document:
  the core nouns and verbs of the system (work order, appointment, bay, reschedule, etc.).
• Abbreviations and acronyms:
  internal shorthand like ADR, RBAC, SSO, WS, SSE, OLTP.
• Architecture-specific terms and concepts you use repeatedly:
  for example “source of truth”, “degraded mode”, “idempotency key”, “read model”.
• Homonyms: words that look the same but mean different things in different contexts
  (for example “order”, “status”, “sync”).
• Synonyms: different words your team uses for the same concept.
  Pick one canonical term and document the alternatives as aliases.
• Ownership of meaning:
  when a term is a contract with an external neighbor, link to where it is specified (chapter 3 or an API spec).
• Translations and language mapping when the domain and the document use different languages:
  a consistent mapping from “local language term” ↔ “document term” so the whole team speaks the same language.

What does not belong here:

• Long tutorials or deep technical explanations.
  Keep definitions short and link to a concept section (chapter 8) when more detail is needed.
• A duplicate of the full domain model.
  If you need the full model, link to it, and keep chapter 12 as the shared vocabulary summary.
• Terms that are obvious to your audience and only used once.
  If it is not used, it does not belong.
• API field definitions and payload-level vocabulary.
  API reference docs have their own glossaries. Chapter 12 covers architecture-level terms, not message schemas.

Abbreviations are not enough

It is common to treat the glossary as an acronym list. That helps, but it does not solve the harder problem: shared understanding.

A better checklist for adding items:

• Does this term show up in multiple chapters?
• Could two stakeholders interpret it differently?
• Is this term used as a contract with a neighbor system?
• Would a new team member stumble on it?

If the answer is yes, it belongs here.

Translations and mixed-language domains

Some domains are bilingual by nature: the business uses Dutch terms, the code uses English, and the document ends up mixing both.

If your team runs into this, document the mapping explicitly.

A practical approach:

• Pick one primary term for the document (usually the one used in code).
• Add the alternative term as an alias.
• If needed, add a short note on where the term is used (UI label, code name, external system name).

This reduces friction in discussions and prevents subtle misunderstandings.

The minimum viable version

If you are short on time, aim for this:

• 5–10 terms: only the ones that are used repeatedly or can be misunderstood.
• 1–2 lines per term.
• Include acronyms that appear in headings, diagrams, or tables.

That is enough to make the document readable for newcomers.

Copy/paste structure (Markdown skeleton)

Use this as a starting point.

## 12. Glossary

<Short intro: what kinds of terms are defined here?>

### Terms and Abbreviations

<!-- Alphabetical order is not required, but most readers like it. -->

- **<Term or abbreviation>**
  <Meaning or description. Notes or aliases go here.>
- **<ABBREVIATION>**
  _<Full form>_
  <Meaning or description.>

### Translations (optional)

<Only if your domain and document use different languages.>

| Term (document) | Term (domain / UI) | Notes |
| :-------------- | :----------------- | :---- |
| ...             | ...                | ...   |

Example (Pitstop)

Pitstop is my small demo system for this series. It is intentionally simple, so the documentation stays shareable.

Below is a short example excerpt.

12. Glossary

Terms and Abbreviations

• ADR
  Architecture Decision Record
  A document that captures an important architectural decision, its context, and its consequences. Stored in chapter 9 of this document.
• Appointment
  A scheduled time slot owned by the Planning Service. Pitstop imports this and maps it to a work order.
  External term; owned by the Planning Service (see chapter 3). Also referred to as “slot” in the Planning API.
• Degraded mode
  A mode where the workshop UI can continue during connectivity loss. Uses a local queue and replay.
• Idempotency key
  A key that makes repeated messages safe to process multiple times. Prevents duplicate state changes on retries.
• RBAC
  Role-based access control
  A model that restricts system access based on the roles assigned to users.
• Source of truth
  The system that owns the authoritative state for a concept. Planning owns appointments, Pitstop owns work order status.
• Status
  In Pitstop, “status” always means work order status (the lifecycle from created → in-progress → done).
  The Planning Service uses “status” for appointment state (confirmed, cancelled, no-show), and the sync layer tracks its own sync status (pending, synced, failed).
  When reading this document, assume work order status unless the text says otherwise.
• SSE
  Server-sent events
  A server push technology that lets a server stream events to a browser over a single HTTP connection.
• Work order
  The unit of work in the workshop. Contains tasks, status, notes, and audit trail. Central aggregate (see chapter 8).
• WS
  WebSocket
  A protocol that provides full-duplex communication over a single TCP connection.

Translations

Term 🇺🇸 (document)	Term 🇳🇱 (domain / UI)	Notes
Work order	Werkorder	UI label used by garages.
Workshop	Werkplaats	Used in training materials and onboarding.

To browse the full Pitstop arc42 sample, see my GitHub Gist.

Common mistakes I see (and made myself)

1. Only listing acronyms
   Acronyms help, but they do not solve shared meaning for domain terms.

2. Defining terms that are never used
   A glossary is part of the architecture document, not a trivia list.

3. Definitions that are too long
   If a definition needs a page, you probably need a concept section (chapter 8) and a short summary here.

4. No alias handling
   If the same concept has two names, document both. Otherwise your team will keep arguing about words instead of system behavior.

5. Not maintaining it
   Every time you introduce a new recurring term, update the glossary. It is cheap work with high return. A practical trigger: review the glossary whenever you write an ADR, add an integration, or onboard a new team member.

Done-when checklist

🔲 Key domain terms used across the document are defined.
🔲 Acronyms and abbreviations are explained.
🔲 Ambiguous terms have explicit meaning for this system.
🔲 Mixed-language terms have a clear mapping (if relevant).
🔲 A new team member can read the document without asking “what does this mean?” repeatedly.

Next improvements backlog

• Add links from glossary terms to the first chapter where they are introduced.
• Add aliases for terms used in UI labels, code, and external systems.
• Review the glossary with a stakeholder who did not write the document.

Wrap-up

Chapter 12 is short, but the return is real. When the glossary is good, every other chapter becomes easier to read and easier to discuss.

This concludes the arc42 template itself.
The series is not done though.

Next up: After the 12 chapters: keep your arc42 docs alive, where I cover where to store the docs, how to review them, how to avoid drift, and how to use agents as guardrails.

This post is about chapter 11: Risks and technical debt, the first chapter in the “Reality and shared language” group.

The first ten chapters built up the architecture story: goals, constraints, structure, runtime, deployment, concepts, decisions, and quality scenarios.

Chapter 11 is where we stop pretending everything is solved. It is where I write down what can still go wrong, what we knowingly postponed, and what we have not figured out yet.

What belongs in chapter 11 (and what does not)

Chapter 11 of an arc42 document answers:

What can still hurt us later, and what are we doing about it?

What belongs here:

• Architecturally relevant risks, including:
  • product and adoption risks (does the workflow fit reality?)
  • integration risks (vendor stability, contract changes, rate limits)
  • operational risks (backup, monitoring gaps, single points of failure)
  • security and compliance risks (data exposure, audit gaps, retention)
  • performance and scalability risks (hot paths, growth limits)
• Technical debt that affects maintainability, reliability, or delivery speed: the things you deliberately postponed that now need a visible trail.
• For each risk or debt item:
  • a clear statement
  • why it matters (impact)
  • how likely it is (roughly)
  • mitigation or next step
  • owner (a person, role, or team)
  • trigger or early warning (optional): how will you know this risk is starting to happen? This is different from mitigation: it is the signal that tells you to act. Think: a metric crossing a threshold, an error rate spike, a support ticket pattern.
• Cross-links to the rest of the document: constraints in chapter 2, strategy in chapter 4, runtime scenarios in chapter 6, deployment assumptions in chapter 7, reusable concepts in chapter 8, decisions in chapter 9, and quality scenarios in chapter 10.

What does not belong here:

• A full project management backlog. Keep chapter 11 focused on items that can materially impact the architecture.
• Sensitive vulnerability details in public documentation. It is fine to record security risks at a high level, but do not publish exploit steps, internal endpoints, or secret material. Link to a private ticket or security register if needed.
• A duplicate of chapter 9. Decisions belong in chapter 9, risks and debt belong here. When a risk is addressed by a decision, link to the ADR.

Risks vs technical debt

A simple distinction that works well:

• A risk is something that might happen. You manage it with mitigation, monitoring, and contingency plans.
• Technical debt is something that already happened. You chose a shortcut or postponement, and it has an interest rate.

Both are normal. Hiding them is what hurts.

Open questions and postponed decisions

Postponing architectural choices is often a very good practice. You wait for more certainty, more feedback, and more clarity before committing.

But not making a decision is also a risk. At best, you forget it still needs to be made. At worst, someone assumes it is already decided and starts building based on that assumption.

I use chapter 11 to make those “not-yet-decided” topics visible. It is not only a risk list, it is also a lightweight backlog of decisions that still need daylight.

The minimum viable version

If you are short on time, aim for this:

• 3–5 risks that could realistically derail delivery, operations, or stakeholder trust
• 3–5 technical debt items that you know will slow you down later

That is already enough to stop surprise work. You can always add more later.

Copy/paste structure (Markdown skeleton)

Use this as a starting point.

## 11. Risks and technical debt

Risks are phrased as: _what could hurt us_ + _why it matters_ + _what we will do about it_.

| Risk / debt item | Why it matters | Mitigation / decision |
| :--------------- | :------------- | :-------------------- |
| ...              | ...            | ...                   |

<!-- add likelihood, owner, trigger columns when your process is ready -->

### Known technical debt (optional)

- <intentional shortcut> → <why acceptable now> ; <when to revisit>
- ...

If you are more serious about risk management, you can add likelihood and impact columns as in a risk matrix, and maybe even assign an owner.

Example (Pitstop)

Pitstop is my small demo system for this series. It is intentionally simple, so the documentation stays shareable.

Below is a small example list. It is not meant to be complete, it is meant to show the style and the level of detail.

11. Risks and technical debt

Risks are phrased as “what could hurt us” + “what we will do about it”.

Risk / debt item	Why it matters	Mitigation / decision
Integration ambiguity per Planning Vendor	Each vendor has different semantics (cancellations, reschedules, no-shows), causing inconsistent work orders	Define a vendor mapping spec + contract tests; keep vendor-specific logic in adapters
Offline sync conflicts	Workshop can update while foreman/admin also edits → conflict resolution can become messy	Keep conflict rules simple (append notes; validate status transitions); provide “needs foreman review” path
Backlog growth in sync queue	Vendor outage or slow API can pile up updates, delaying customer comms	Monitor sync_queue_depth; circuit breaker; dead-letter queue + ops playbook
WebSocket instability in harsh networks	Real-time UX can degrade unpredictably in garages	Configurable fallback to polling (Realtime:FallbackToPollingSeconds); reconnect UX; track disconnect rates
Audit log volume / reporting load	Auditability creates data; dashboards can overload OLTP queries	Use read models; partition audit table; retention policies; optional replica for reporting

Known technical debt (intentional for v1)

• Single backend instance per garage (no HA) → acceptable for v1; revisit for chains.
• Minimal conflict resolution UI → acceptable initially; prioritize based on observed conflicts.

To browse the full Pitstop arc42 sample, see my GitHub Gist.

Common mistakes I see (and made myself)

1. Treating this as a shame list
   Chapter 11 is not for blame. It is for visibility and prioritization.

2. No owners
   A risk without an owner is a wish. Put a person, role, or team on it.

3. No next step
   A risk without a mitigation is just anxiety in table form. Even “decide in ADR-007” is better than nothing.

4. Only technical risks
   Adoption, workflow fit, vendor behavior, and operations are often where the real pain starts.

5. Deleting history
   Close items explicitly. If something was a risk and it is no longer a risk, document why.

6. No links back to the architecture story
   Risks should connect back to the drivers and trade-offs. Otherwise the list becomes isolated and nobody acts on it.

Done-when checklist

🔲 The chapter lists the risks that could realistically hurt delivery or operations.
🔲 Technical debt items are visible, not hidden in chat and backlog noise.
🔲 Each item has an owner and a next step.
🔲 Items link to the relevant chapters, concepts, decisions, or scenarios.
🔲 The list is reviewed on a cadence (even if it is just “every release”).

Next improvements backlog

• Add a simple severity sorting (impact × likelihood) to focus discussions.
• Add a trigger column to your table once the basic list is stable.
• Link security risks to a private register when details should not be published.

Wrap-up

Chapter 11 is what keeps the architecture document honest. You make risks and debt visible early, then refine them as you learn.

Next up: arc42 chapter 12, “Glossary”, where we build shared language so readers do not have to guess what terms mean.

This post is about chapter 10: Quality requirements, the third chapter in the “Reusables, decisions, and qualities” group.

Chapter 1 introduced quality goals at a high level. Chapters 8 and 9 captured patterns and decisions that often exist because of those goals. Chapter 10 is where I make qualities concrete: not as slogans, but as scenarios you can test, monitor, and verify.

One recurring problem: stakeholders and teams find it hard to write SMART quality requirements. They will say fast, robust, secure, and everyone nods. Then production teaches you that nodding is not a measurement.

What belongs in chapter 10 (and what does not)

Chapter 10 of an arc42 document answers:

Which quality requirements matter, and how do we know we meet them?

What belongs here:

• A quality requirements overview:
  the relevant quality characteristics for your system, grouped in a structure that is easy to scan. ISO/IEC 25010 is a common choice for this grouping, and Q42 is a useful catalogue for examples.
• A set of quality scenarios:
  situation-based, testable requirements with a stimulus, an expected response, and a metric or target. “Testable” means different things per type: validate a latency scenario with a load test or SLO alert; an auditability scenario with a timed export; a modifiability scenario by verifying the adapter boundary in a code review.
• A clear link back to quality goals from chapter 1.
  If chapter 1 says “auditability” is a top goal, chapter 10 should make that measurable.
• Cross-links to where quality is implemented:
  concepts (chapter 8), decisions (chapter 9), and sometimes deployment constraints (chapter 7).

What does not belong here:

• A technology shopping list.
  ”Kafka” is not a quality requirement, it is a potential solution.
• Purely functional requirements and business workflows.
  Those belong in use cases, building blocks (chapter 5), and runtime scenarios (chapter 6).
• Only vague adjectives.
  ”fast” and “secure” are direction, not requirements. Chapter 10 is where you turn them into something you can validate.

Why is quality so late in arc42?

It can feel strange that quality scenarios show up this far back in the arc42 structure. It can look like quality is an afterthought. It is not.

This is how I explain it:

• Quality goals are up front because they drive direction.
• Quality scenarios are later because they need context to be meaningful.
• The document is iterative: you refine goals, you make choices, you learn, you tighten scenarios.

In other words, chapter 10 benefits from having chapters 5–7 in place. A scenario like “p95 status update latency is ≤ 2s” only makes sense when you know what “status update” is, which building blocks collaborate, and where the system actually runs.

A structure that helps when people struggle with SMART qualities

If your stakeholders struggle with SMART wording, do not fight them with a blank page. Give them a ladder:

• Start with a quality tree to agree on vocabulary.
• Add a short overview per quality area: what matters and what does not.
• Convert the important items into scenarios with measurable targets.

Two helpful sources for vocabulary and inspiration:

• ISO/IEC 25010:2023 gives you a familiar top-level structure.
• Q42 is a companion project by the arc42 team. It gives you a large catalogue of quality characteristics with descriptions and example requirements you can adapt.

Use them as scaffolding, not as a checklist.

Quality tree diagram

A quality tree is a visual overview of which quality characteristics apply to your system. It works like a map: it shows the landscape at a glance, so you can decide where to focus.

It is useful because it makes trade-offs visible. When you can see all quality areas together, it becomes easier to say “this matters more than that”, and to explain that choice to others. It also prevents the “everything is important” trap: when everything is marked as a top priority, that is the same as having no priorities at all.

The minimum viable version

If you are short on time, aim for this:

1. A small quality overview, grouped by ISO/IEC 25010:2023 headings.
   (or your own headings if that reads better).
2. Pick 3–6 top items and write quality scenarios for them.
3. For each scenario, add a metric target you can validate later.

That is enough to stop quality from being a vibe.

Copy/paste structure (Markdown skeleton)

Use this as a starting point.

## 10. Quality requirements

<Short intro: why quality matters for this system and how we verify it.>

### 10.1 Quality requirements overview

<Group requirements using ISO/IEC 25010:2023 headings or another clear structure.>
<Mark "nice-to-have" items explicitly.>

### 10.2 Quality scenarios

<Scenario-based, testable requirements. Keep them short and measurable.>

| Scenario | Stimulus | Response | Metric/Target |
| :------- | :------- | :------- | :------------ |
| ...      | ...      | ...      | ...           |

<Add more tables per quality theme if that improves readability.>

Example (Pitstop)

Pitstop is my small demo system for this series. It is intentionally simple, so the documentation stays shareable.

Below is a shortened version of the Pitstop chapter 10. It shows the structure without drowning you in every possible scenario. Notice how overview headings and scenario groups mark which chapter 1 top goals they address. Consistency is a Pitstop-specific quality area that does not map to a single ISO/IEC 25010:2023 category.

10. Quality requirements

10.1 Quality requirements overview

Reliability (top goal: Resilience)

• Degraded-mode operation for workshop during flaky internet.
• Sync backlog does not block workshop core operations.

Consistency (top goal: Consistency)

• Status updates visible across all UIs within seconds.
• Idempotent handling of duplicate planning updates.

Maintainability (top goal: Modifiability)

• Add a new planning vendor adapter without changing core work order rules.
• Nice-to-have: automated contract tests with recorded fixtures.

Security

• Role-based access control with site scoping via garageId.
• Secure audit trail, prevent tampering with history.

Auditability / traceability

• Every significant change records who, when, and why.
• Timeline export supports disputes and compliance.

10.2 Quality scenarios

Reliability (top goal: Resilience)

Scenario	Stimulus	Response	Metric/Target
Wi-Fi outage	15 min disconnect	Workshop continues, actions queued locally	≥ 99% of actions queued without loss
Reconnect	Network returns	Queue replays and sync completes	drained within ≤ 60s

See also: degraded mode concept and ADR-001.

Consistency (top goal: Consistency)

Scenario	Stimulus	Response	Metric/Target
Status visible everywhere	Mechanic sets WaitingForParts	Admin and Workshop converge	≤ 2s end-to-end (p95)
Duplicate vendor update	Planning sends same appointment twice	Processed once, idempotent	0 duplicate work orders

Maintainability (top goal: Modifiability)

Scenario	Stimulus	Response	Metric/Target
Add planning vendor	New API and mapping	Add adapter, domain unchanged	≤ 2 days, core untouched

Security

Scenario	Stimulus	Response	Metric/Target
Cross-garage access	User tries other garageId	Denied	100% blocked
Audit tamper attempt	Try to edit history	Prevented + logged	100% blocked + logged

Auditability

Scenario	Stimulus	Response	Metric/Target
Customer dispute	”You promised 16:00”	Export full timeline	≤ 60s export

To browse the full Pitstop arc42 sample, see my GitHub Gist.

Common mistakes I see (and made myself)

1. Writing only adjectives
   ”fast” is not a requirement. A scenario with a measurable target is. Make sure to talk with stakeholders what the target should be and how to verify it.

2. Mixing requirements and solutions
   ”use Redis” is a decision, not a requirement. The requirement is something like “fast access to work order state”. If you have a decision that implements a quality requirement, write the requirement here, and link to the decision in chapter 9.

3. No link back to goals
   If chapter 1 lists top goals, chapter 10 should make them concrete. It would be strange if chapter 1 says “consistency” is a top goal, but chapter 10 does not have any scenarios to measure it.

4. Treating this as one-and-done
   Quality scenarios improve with iteration. Early drafts are allowed to be rough, as long as you refine them. Every time you add a scenario, building block, deployment, or decision, ask yourself if it has quality implications that should be captured here.

5. Too many scenarios without navigation
   A large system can have many scenarios. Group them, keep titles clear, and keep tables consistent. Link to documents if you have detailed test plans or runbooks.

Done-when checklist

🔲 Quality requirements are grouped in a structure people recognize (ISO/IEC 25010 or equivalent).
🔲 Top quality goals from chapter 1 are turned into measurable scenarios.
🔲 Scenarios include a stimulus, response, and a metric or target.
🔲 At least one quality area traces back to the concept or decision that implements it.
🔲 The chapter is treated as iterative, it will be refined as the system and insights evolve.

Next improvements backlog

• Add monitoring or test hooks for the most important scenario metrics.
• Add scenario coverage for important external neighbors and operational jobs.
• Tighten targets over time based on observed production baselines.
• Add a short note per top goal on how it is validated (test, metric, runbook).

Wrap-up

Chapter 10 is where quality stops being a wish and becomes a check. When a quality trade-off is accepted, document it here: note which quality was deprioritized, which won, and link to the decision in chapter 9 that captures the reasoning. You can start with rough scenarios, then refine them as you learn.

Next up: arc42 chapter 11, “Risks and technical debt”, where we capture the things that can still bite us later, and how we keep them visible.