diagramming-processes

绘制流程图

必备背景知识：technical-writing 技能（硬性规则、真实性规则、风格）。

概述

图表是以图示而非文字表达的一组论断；每个方框和箭头都受与句子相同的真实性规则约束。核心原则：**绘制行为（流程、生命周期、交互），将源文件纳入版本控制，并将每次渲染都视为派生产物。**文字说明负责阐述推理；图表则呈现文字难以清晰表达的内容：分支、并发和状态。

何时使用，何时不使用

需要展示流程、生命周期或交互时使用：跨组件或组织的业务流程、状态机、消息交换，或遗留项目的 processes.md（documenting-legacy-codebases）。不要把图表当装饰：线性流程若只有三四个步骤，应使用编号列表；用图表重述这样的列表只是摆设。不在适用范围内的内容：由数据生成的图表（指标、趋势），以及实现结构，后文的行为规则禁止绘制这类结构。

表示法阶梯

绘制前先确定抽象层次，并选择与之匹配的表示法：

• **业务层：ArchiMate。**适用于跨部门、组织或多个系统的流程、能力地图，以及企业利益相关者期待的 TOGAF 风格视图。受众关注角色、服务和流程，而非组件。
• **系统层：PlantUML 行为图。**适用于系统内部及系统之间的流程、状态机和时序图：代码文档，比代码高一个层次。
• **代码层：不使用图表。**类和包结构应由代码本身呈现；IDE 可按需生成比任何已提交图表都更新的视图。

阶梯决定表示法和词汇，但不决定工具：一套工具链可同时用于两个层次，因为 PlantUML 的标准库包含 ArchiMate 表示法。仓库使用的工具应在“源文件，而非图片”一节中统一确定。

源文件，而非图片

• 源文件是提交到版本控制的文本，使用仓库已有的图表工具。若尚未确定工具，默认使用 PlantUML（标准库丰富，且包含 ArchiMate）；若选择确实尚未确定，应询问负责人，并推荐 PlantUML。核心技能的 references/truth.md 规定了基本原则：渲染产物是派生内容；过时的渲染产物应删除，而不是留着误导读者。
• 每个源文件只包含一张图，以所展示的流程命名，并与相关文档一起放在一个图表目录中。
• 渲染必须使用仓库维护的工具（脚本、make 目标或构建步骤），由负责人设置，而不是由图表作者设置。若缺少此类工具，应告知负责人；绝不要绕过这个问题，改用托管平台恰好支持内嵌渲染的表示法。
• 使用一条仓库命令渲染所有图表；除非托管平台已能渲染仓库选用的源格式，否则应提交渲染产物。源文件变更时，应在同一次修改中删除过时的渲染产物，并在索引中记录缺失的渲染产物，直到重新生成。
• 如果截图、导出的图片或白板照片没有对应源文件，就应记录为包含它的文档中的问题：无人能比较差异，因此无人会维护它。

根据读者的问题选择图表类型

根据读者提出的问题选择图表类型；每张图只回答一个问题：

读者的问题	绘制内容
这个流程如何在整个组织中运行	ArchiMate 业务流程视图
会发生什么、顺序如何、需要作出哪些决策	活动图
这个事物可能处于哪些状态，什么会推动状态变化	状态机
谁与谁通信、顺序如何、传递什么消息	时序图
这个领域中有哪些事物，它们之间有什么关系	概念图，以业务对象为层次

一张图若要回答两个问题，就等于两个都没回答；应拆分图表。若图表需要为自创符号单独配一份图例，就说明它试图回答太多问题。

行为，而非实现

documenting-legacy-codebases 中的重构测试同样适用于图表，而且图表比段落更容易掩盖偏差：

• 参与者是系统、角色、模块和业务对象。 类、方法和函数应留在代码中（参见阶梯）。
• 边应使用领域语言标注事件或条件：“付款已确认”，而不是回调名称。守卫条件可以使用配置键，因为配置键属于契约表面；但绝不能使用方法名称。
• 标题应命名流程，而不是规范、阶段或计划：不讲述交付过程的硬性规则同样适用于图表源码，包括注释。
• 行为存在差异的错误和异常路径应绘出，并且应能清楚区分；对于确实存在失败分支的流程，只画顺利路径会夸大其情况。
• 怪异之处应绘出，而且本身就是内容。 无法离开的状态、针对某个输入跳过某一步的流程：这些出人意料的分支正是图表值得存在的原因（documenting-legacy-codebases，怪异之处）。

图表索引

图表超过 5 个时，应在旁边放置一份索引文档，并根据文件重建该衍生文档（核心事实规则）：

• 覆盖表：每张图表展示什么、其源文件、已提交时的渲染图，以及其状态。
• 每张图表对应的模块，作为偏差锚点：图表指向代码的唯一位置。
• 渲染命令，使索引同时也是构建说明。
• 按源文件列出的待渲染项，以便将缺少渲染图视为已跟踪的状态，而非悄然留下的缺口。

维护

会改变流程的改动，应在同一次改动中更新对应的图表源码：图表属于文档，而文档是完成工作的一部分（核心事实规则）。渲染是图表的编译步骤：源码编辑可能造成语法错误，而错误只有在运行渲染时才会显现。作者应在提交改动前进行渲染；如果仓库尚缺少相应流水线，手动运行一次工具即可满足此项检查。移除功能时，应在同一次改动中处理说明文字、图表源码、索引条目和已提交的渲染图。如果没人愿意更新某张图表，说明它试图回答的问题太大；应沿着可独立变化的界限将其拆分。

验证

图表中所有可读内容都是一种断言（核心事实规则），因此图表应像说明文字一样以事实为依据并经过审查：

• 作者应在绘制前，根据代码核实每个框、箭头和守卫条件。未经确认、仅凭推断得出的流程，应在嵌入该图表的文档中标注为推断，绝不能默默将其画成事实。
• 审阅者应对照实际行为阅读图表，并审阅源文本而非图片：后续编辑者要修改的是源文本。
• 图表源码和说明文字一样会产生偏差，也应纳入每一次遗留代码维护行动：该行动（documenting-legacy-codebases）应将图表源码与嵌入它们的文档一并作为事实依据。
• 每项事实的图表及其周围说明文字应有各自明确的分工：说明文字解释流程为何存在以及需要注意什么，图表展示流程；双方都不应逐步复述对方的内容。