methodatlas
Playbook

Build Architecture Documentation

Move from scattered architecture knowledge to views, decisions, and communicable documentation.

Outcome

A living architecture documentation with views, rationale, communication plan, and maintenance ownership.

At the end you have

Architecture DocumentC4 DiagramsArchitecture ViewsCommunication Canvas

Decision point

You can decide which architecture information should be documented, maintained, and communicated as authoritative.

Next step

Publish the documentation structure, set maintenance owners, and establish review rhythm.

Ideal for

  • Onboarding
  • architecture reviews
  • systems with growing complexity

Not good for

  • throwaway prototypes
  • documentation without maintenance owner
Preparation

What should be clear before you start

Roles

  • Architect or tech lead
  • System and team owners
  • documentation target audiences

Inputs

  • existing architecture artifacts
  • known onboarding or review pain points
  • key systems, decisions, and stakeholders

Setup

  • Clarify documentation goal
  • Choose storage and maintenance process
  • Collect main target audiences and questions
Flow

Method path

0 methods
    Completion criteria
    Templates

    Artifacts for this playbook

    Artifacts stay collapsed until you actually need them.

    MarkdownShow template

    arc42 Working Template

    Compact working template for arc42 with context, input, output artifacts, and next step.

    # arc42 Working Template

## Goal

Pragmatic template for structured, living software architecture documentation.

## Context

When and for what do we use this method?

## Input

Which data, observations, decisions, or materials are available?

## Execution

Short notes along the runsheet.

## Output artifacts
- Architecture Document:
- Context View:
- Runtime View:
- Deployment View:

## Assumptions and open questions

- ...

## Decision / Next step

Owner, date, and success signal.
    CanvasShow template

    C4 Model Working Template

    Compact working template for C4 Model with context, input, output artifacts, and next step.

    # C4 Model Working Template

## Context

What is this method used for?

## Core question

Which question should be answered at the end?

## Input

Which data, observations, or materials are available?

## Working area

- Area 1:
- Area 2:
- Area 3:
- Relationships / patterns:

## Output artifacts
- Context Diagram:
- Container Diagram:
- Component Diagram:

## Open questions

- ...

## Next step

Owner, date, success signal.
    MarkdownShow template

    ADR Markdown Template

    Compact template for architecture decision records in a repository or wiki.

    # ADR-0001: Decision Title

**Status:** proposed
**Date:** YYYY-MM-DD
**Decider:** First Last
**Trigger:** Ticket, incident, or RFC

## Context

What situation makes the decision necessary? Which constraints, quality attributes, or earlier decisions matter?

## Options

### Option 1: ...
- Pros:
- Cons:

### Option 2: ...
- Pros:
- Cons:

## Decision

We decide to ...

## Consequences

Positive consequences:
- ...

Negative consequences and risks:
- ...

Follow-up ADRs or tickets:
- ...