文档、图示与表达
一、架构文档的目的与受众
文档为谁写、解决什么问题，要先想清楚。目的可以是： onboarding 新人、评审决策、运维排查、合规审计、知识沉淀。不同目的对应不同受众（新人、评审专家、运维、合规、后人），内容深度与表述方式也应不同。一份文档试图「什么都写」往往什么都写不好；按受众拆成「概览」「决策记录」「运维手册」等更有效。
Onboarding、评审、运维、合规、沉淀……不同目的对应不同篇幅与重点。先定「这份文档要解决什么」，再写。
- 概览：系统做什么、边界在哪
- 决策：ADR、选型与取舍
- 运维：部署、监控、应急
新人要「从哪看起」；专家要「决策与约束」；运维要「怎么操作」。同一系统可有多份视图，不必塞在一份里。
- 术语与抽象层次匹配读者
- 入口与目录清晰、可检索
二、C4、UML 与自洽图例
C4 Model（Context, Container, Component, Code）把架构图分成四层：Context 是系统与外部用户/系统的关系；Container 是系统内主要应用或服务；Component 是容器内的模块/组件；Code 是类级（可选，常由代码生成）。一层一图、逐层下钻，避免「一张图塞满所有东西」。UML 适合类图、时序图、状态图等，在需要精确语义时用；若团队不熟 UML，用自洽图例（自己定义框、线、箭头含义，并在图旁注明）也行，关键是图例一致、读者能懂。
图例要自洽：同一文档（或同一类型图）里，方框、箭头、颜色含义一致，并在图旁或文末用简短图例说明，避免「只有画图的人懂」。
三、文档即沟通：保持精简、与代码/实现同步
文档是沟通媒介，不是存档仓库。原则：精简（只写读者需要的，能删则删）、与实现同步（代码/部署变了，文档要更新或标注「以代码为准」）、可发现（标题、目录、关键词便于搜索）。过期文档比没文档更糟——会误导人。若暂时无法同步，至少注明「最后更新时间」和「若与代码冲突以代码为准」。
文档原则
- 精简： 按目的与受众写，能一句话说清不写一段；删除重复与废话。
- 同步： 代码/架构变更时更新文档，或把文档放在代码库内由 MR 一起改；过期要标注或归档。
- 可发现： 清晰标题、目录、关键词；重要决策用 ADR 并带可检索的标签。
四、图表类型选择：结构、流程、时序
不同问题用不同图：结构图（组件/服务/模块的静态关系，谁依赖谁）适合表达「系统长什么样」；流程图（步骤、分支、状态）适合表达「业务或流程怎么走」；时序图（谁在何时调用谁）适合表达「一次请求的调用链」。选错类型会让读者费解；一页里混用多种图例也容易乱，建议同一页同类型、图例统一。
表达「是什么、谁和谁有关」：组件、服务、依赖关系。
- C4 各层、部署图、依赖图
表达「步骤与分支」：业务流程、状态机、审批流。
- 泳道图、流程图、状态图
表达「谁在何时调谁」：请求链路、交互顺序。
- 时序图、调用链、消息顺序
五、书面表达的逻辑与可检索性
书面表达要逻辑清晰：结论先行、论据支撑、段落有主题句；长文档要有目录与层级。可检索：关键决策、术语、系统名等便于搜索；ADR 标题与标签统一，方便「为什么选 XX」时搜到。避免大段无小标题的流水账，也避免只有图没有简要文字说明。
表达与可检索
- 结论先行，再展开理由与细节。
- 段落有主题句，长文档有目录与锚点。
- 关键决策、系统名、术语便于全文搜索；ADR 编号与标签一致。
要点： 文档先定目的与受众，再写内容；用C4 或自洽图例分层画图；精简、同步、可发现；按问题选结构/流程/时序图；书面表达逻辑清晰、可检索。
反例：文档又长又旧，图例不一，没人用。
某系统有一份 80 页的「架构说明」，从背景到细节全塞在一起，没有按受众拆分；新人不知道从哪看起，老人也懒得翻。图是几年前画的，已经多了两个新服务、拆了一个库，图上都没有；运维按图排查时被误导。再如：同一份文档里，有的图方框表示「服务」，有的图方框表示「数据流」，没有图例，读者只能猜。正确做法：拆成「5 分钟概览」「决策记录」「运维手册」；图随代码或发布更新，或注明「以代码/部署为准」；图例统一并在图旁注明。文档没人用，往往是因为目的不清、过期、难找。
小结： 架构文档要明确目的与受众，按需拆分内容。用C4 或 UML 或自洽图例画图，图例一致。文档精简、与实现同步、可发现；按问题选结构/流程/时序图；书面表达逻辑清晰、可检索，让文档真正成为沟通与传承的工具。
六、小结
文档、图示与表达是架构沟通的基础。明确目的与受众；用C4、UML 或自洽图例、一层一图；文档精简、同步、可发现；按问题选结构/流程/时序图；书面逻辑清晰、可检索。下一章进入沟通与影响：向上管理——对齐目标与争取资源。