1---2name: activity-diagram3description: Choose an activity diagram when the user needs to explain workflow logic, parallel work, decisions, joins, and responsibility across actions.4---56# Activity diagram78## What and why910An activity diagram tells how work flows through actions and control nodes, including branching, merging, concurrency, and synchronization. Use it for algorithms, operational workflows, and cross-team procedures. Use BPMN when formal business-process events, messages, compensation, or executable process semantics matter.1112## Model it13141. Define the activity boundary, initial condition, and completion criteria.152. Name actions with concise verbs and separate control flow from data flow.163. Use decision/merge and fork/join deliberately; a fork must have a meaningful synchronization story.174. Add swimlanes only to answer ownership questions; keep lane count small.185. Show exceptions, cancellation, and parallel completion rules when they affect the outcome.1920UML 2.5.1 provides the activity, action, control-node, token-flow, and partition concepts. See [UML activities](references/uml-activities.md).2122## Story and styling2324Give the happy path a stable reading direction and make concurrency visually parallel. Label guards as business conditions, not code fragments. Use lanes as responsibility bands, and reserve color for ownership or exception emphasis with a textual legend.2526## Renderer routing2728Prefer `plantuml` for UML activity semantics, `mermaid` for accessible documentation flow, `actdiag` for simple lane-oriented activities, or `d2` for a customized technical workflow. Preserve the user's requested renderer. Use `bpmn` for formal process interchange rather than translating BPMN semantics into a generic activity chart.2930## Review3132- Are actions, decisions, merges, forks, and joins distinguishable?33- Does every parallel branch have a clear completion or cancellation rule?34- Are swimlanes meaningful and consistently assigned?35- Are data objects shown only when they clarify the workflow?36- Can a reader follow normal, exception, and concurrent paths?3738## Limits and opportunities3940diagram.zip does not validate UML token-flow semantics or guarantee that an activity is deadlock-free. A UML activity parser/linter and a first-class swimlane layout profile would be useful future integrations.