diagramming-processes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Diagramming processes

流程图表绘制

REQUIRED BACKGROUND: the

technical-writing

skill (hard rules, truth rules, style).

必备背景知识：

technical-writing

技能（硬性规则、真实性规则、风格规则）。

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.

当需要展示流程、生命周期或交互时使用：跨组件或跨组织的业务流程、状态机、消息交互、旧有项目的

processes.md

文档（

documenting-legacy-codebases

技能场景）。禁止用于装饰： 仅包含三到四个步骤的线性流程应使用编号列表，重复该内容的图表属于冗余内容。由数据生成的图表（指标、趋势）不在本技能范围内，绘制实现结构的图表也被下文的行为规则禁止。

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.

根据展示层级匹配符号，绘制前先明确层级：

业务层：ArchiMate：跨部门、跨组织或多系统的流程、能力图谱，以及企业相关方期望的TOGAF风格视图，需使用ArchiMate符号绘制。受众关注角色、服务和流程，而非组件。
系统层：PlantUML行为图表：系统内部及系统间的流程、状态机和序列图。这是代码文档所在的层级，比代码高一级。
代码层：无需图表：类和包结构由代码本身展示，IDE可按需生成比已提交图表更新的视图。

符号层级定义了符号和词汇，工具选择需适配代码库。在代码库中，一套工具链可覆盖两个层级：PlantUML，搭配其ArchiMate插件用于业务层。在文档库或文件夹中，使用已有的图表工具；若无法确定，询问所有者偏好。

Source, not pictures

源代码优先，而非图片

The source is committed text: PlantUML by default, Mermaid where the hosting platform renders it inline. The core skill's
```
references/truth.md
```
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.

提交的内容为文本格式的源代码：默认使用PlantUML，若托管平台支持内联渲染则使用Mermaid。核心技能的
```
references/truth.md
```
规定了基本原则：渲染输出为派生产物，过时的渲染结果需删除，避免误导。
每个源代码文件对应一个图表，以其所展示的流程命名，集中存放在文档旁的一个diagrams目录中。
仓库中的一条命令可渲染所有图表，图表索引会列出这些图表。仅当托管平台无法渲染源代码时，才提交渲染结果；当源代码变更时，需在同一变更中删除过时的渲染结果，并在索引中记录缺失的渲染结果，直至重新生成。
内联嵌入的Mermaid无需渲染步骤：代码块会随其所展示的流程同步更新。
无源代码的截图、导出图片或白板照片属于文档缺陷：无人能对其进行差异对比，因此也无人会维护它。

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.

根据读者的问题选择图表类型，每个图表对应一个问题：

读者的问题	绘制的图表类型
该流程如何在组织内跨部门运行	ArchiMate业务流程视图
会发生什么，顺序如何，涉及哪些决策	活动图
某对象可能处于哪些状态，是什么触发状态变更	状态机图
谁与谁交互，顺序如何，传递什么消息	序列图
该领域存在哪些对象，它们之间有什么关系	概念图（业务对象层级）

一个图表若试图回答两个问题，最终两个问题都无法清晰解答，需拆分。若图表需要自定义符号图例，则说明它试图回答的问题过多。

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
```
, quirks).

documenting-legacy-codebases

技能中的重构测试同样适用于图表，且图表比文字更易隐藏偏差：

参与者为系统、角色、模块和业务对象：类、方法和函数属于代码范畴（见符号层级）。
箭头标注事件或条件，使用领域语言：例如“支付确认”，而非回调函数名称。守卫条件可标注配置键，因为配置键属于契约层面；但绝不能标注方法名称。
标题命名流程：而非规范、阶段或计划：“无交付叙事”的硬性规则同样适用于图表源代码，包括注释。
错误和异常路径需在行为不同处绘制，并加以区分：若一个存在实际失败分支的流程仅绘制快乐路径，属于夸大其词的声明。
特殊情况需绘制并作为内容的一部分：无法退出的状态、针对特定输入跳过步骤的流程：这些意外分支正是图表存在的意义（
```
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.

变更流程时，需在同一变更中更新对应的图表源代码：图表属于文档，文档是完成工作的一部分（遵循核心真实性规则）。渲染也是图表的编译步骤：源代码编辑可能会隐形破坏语法，只有在渲染时才会暴露问题。作者在提交编辑前需进行渲染，或在托管平台中预览内联Mermaid。当功能被移除时，一次变更需涵盖文字内容、图表源代码、索引条目以及已提交的渲染结果。若无人愿意更新某个图表，说明它试图回答的问题范围过大，需按独立变更的边界拆分。

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
```
) grounds the
```
.puml
```
files with the documents that embed them.
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.

根据核心真实性规则，图表中所有清晰可见的内容都是声明，因此图表需像文字内容一样进行验证和审核：

绘制前，作者需对照代码验证每个方框、箭头和守卫条件。若流程是推断而非确认的，需在嵌入图表的文档中标注为推断内容，绝不能默认为事实绘制。
审核者需对照行为审核图表，且审核的是源代码而非图片：源代码是后续编辑者会修改的内容。
图表源代码会像文字内容一样出现偏差，需纳入所有旧有项目：项目（
```
documenting-legacy-codebases
```
）将
```
.puml
```
文件与嵌入它们的文档关联起来。
图表及其周围的文字内容需为每个事实共享同一来源。文字内容说明流程存在的原因和注意事项；图表展示流程，两者无需逐步骤重复。