Diagramming processes

REQUIRED BACKGROUND: the technical-writing 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 processes.md 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.