Diagramming processes
REQUIRED BACKGROUND: the
skill (hard rules, truth rules, style).
Overview
A diagram is a set of claims drawn instead of written, and every box and arrow is bound by the same truth rules as a sentence. Core principle: diagram the behavior (processes, lifecycles, interactions), keep the source in version control, and treat every render as derived. The prose owns the reasoning; the diagram carries the structure that prose serializes badly, which is branching, concurrency, and state.
When to invoke, and not
Invoke when a flow, lifecycle, or interaction needs showing: a business process spanning components or organizations, a state machine, a message exchange, the
of a legacy campaign (
documenting-legacy-codebases
). Do NOT invoke to decorate: a linear flow of three or four steps is a numbered list, and a diagram restating one is furniture. Charts generated from data (metrics, trends) are out of scope, and so is diagramming implementation structure, which the behavior rule below forbids.
The notation ladder
Match the notation to the altitude, and name the altitude before drawing:
- Business layer: ArchiMate. Processes that span departments, organizations, or multiple systems, capability maps, and the TOGAF-style views enterprise stakeholders expect are drawn in ArchiMate notation. The audience reads roles, services, and processes, never components.
- System layer: PlantUML behavior diagrams. Flows, state machines, and sequences within and between systems. This is where code documentation lives, one level above the code.
- Code layer: no diagrams. Class and package structure is the code's own to show, and an IDE generates a fresher picture on demand than any committed one.
The ladder sets the notation and the vocabulary; the tool follows the repository. In a code repository, one toolchain serves both rungs: PlantUML, with its ArchiMate plugin for the business layer. In a documentation repository or folder, use the diagram tool already in use there, and when none is discernible, ask the owner which they prefer.
Source, not pictures
- The source is committed text: PlantUML by default, Mermaid where the hosting platform renders it inline. The core skill's owns the ground rule: rendered output is derived, and stale renders are deleted rather than left to mislead.
- One diagram per source file, named for the process it shows, grouped in one diagrams directory beside the documents.
- One repo command renders everything, and the diagram index names it. Renders are committed only where the host cannot render source; when a source changes, its outdated render is deleted in the same change, and the missing render is recorded in the index until regenerated.
- Mermaid embedded inline needs no render step; the block updates in the same change as the flow it shows.
- A screenshot, an exported picture, or a whiteboard photo with no source is a finding against the document that contains it: nobody can diff it, so nobody will maintain it.
The kind answers the reader's question
Pick the diagram kind from the question the reader brings, one question per diagram:
| The reader asks | Draw |
|---|
| How does this process run across the organization | ArchiMate business process view |
| What happens, in what order, with which decisions | Activity diagram |
| Which states can this thing be in, and what moves it | State machine |
| Who talks to whom, in what order, with what messages | Sequence diagram |
| What exists in this domain and how it relates | Concept diagram, at business-object level |
A diagram answering two questions answers neither; split it. A diagram that needs a legend of its own invented symbols is answering too many at once.
Behavior, never implementation
The refactor test from
documenting-legacy-codebases
governs diagrams too, and a diagram hides its drift better than a paragraph does:
- Participants are systems, roles, modules, and business objects. Classes, methods, and functions stay in the code (see the ladder).
- Edges carry the event or condition, in the domain's language: "payment confirmed", never a callback name. A guard may name a config key, because config keys are contract surface; it never names a method.
- Titles name the process, never a spec, phase, or plan: the no-delivery-narrative hard rule applies inside diagram source too, including comments.
- Error and exception paths are drawn where behavior differs, and drawn distinguishably; a happy-path-only diagram of a process with real failure branches is an overstated claim.
- Quirks are drawn, and are content. The state nothing can leave, the flow that skips a step for one input: the surprising branch is the reason the diagram earns its place (
documenting-legacy-codebases
The diagram index
More than five diagrams get one index document beside them, and the index is a derived artifact rebuilt from the files (core truth rules):
- A coverage table: what each diagram shows, its source file, its render if committed, and its status.
- Per diagram, the module it describes, as the drift anchor; this is the one place a diagram points at code.
- The render command, so the index is also the build instruction.
- Pending renders are listed here, named per source, so a missing render is a tracked state rather than a silent gap.
Maintenance
A change that alters a flow updates the matching diagram source in the same change: a diagram is documentation, and documentation is part of done (core truth rules). Rendering is also the diagram's compile step: source edits break syntax invisibly, and the break surfaces only when the render runs. The author renders, or previews inline Mermaid in the host, before shipping the edit. When a feature is removed, one change covers the prose, the diagram source, the index row, and the committed render. A diagram nobody can bring themselves to update is answering too big a question; split it along the seams that change independently.
Verification
Everything legible in a diagram is a claim, per the core truth rules, so a diagram is grounded and reviewed like prose:
- The writer verifies every box, arrow, and guard against the code before drawing it. A flow inferred rather than confirmed is labeled as inference beside the diagram in the embedding document, never silently drawn as fact.
- The reviewer reads the diagram against the behavior, and reviews the source text rather than the picture: the source is what the next editor changes.
- Diagram sources drift like prose and join every legacy campaign: the campaign (
documenting-legacy-codebases
- A diagram and its surrounding prose share one home per fact. The prose says why the process exists and what to look out for; the diagram shows the flow, and neither restates the other step by step.