← 返回全部文章
方法与工具 · 2026-10-16

engineering-docs:先修文档的决定,再修图

9 min read

AI 写的技术文档有两个常见问题:一大段一大段地堆字;流程图把节点从头串到尾,看不出重点。

技术文档是给人看的,阅读效率很关键。好好说话能改善语言,结构还需要单独处理:结论放在哪里,细节怎么查,图里哪些关系必须一眼看清。

核心做法:文字分主次,图画清关系。engineering-docs 把这两件事连起来,同时保留可修改的图源,让后续修改能回到具体内容。

这套能力从技术文档标准和稳定、可编辑的工程图需求起步,后来不断补正文格式、图型、布局、配色和交付检查。下面沿着文字和图两条线,拆开说具体怎么做。

文字结构

文字先解决读者看什么。读者不必从头读到尾,也不该自己从参数、背景和过程里找结论。

阅读层级

把信息分成三层,每层回答不同问题。

层级放什么读者拿走什么
首屏结论、范围、要确认的决定和一张总览图这件事做什么,为什么要做
章节按模块或问题展开,第一段先给本章结论主干怎么做,为什么这样选
实现细节证据、参数、接口、完整规则和测试矩阵需要实现或复查时,能找到依据

负责人关心选什么、接受什么代价;实现者需要职责、接口和失败处理。三层结构让他们各取所需,同时沿着同一套结论往下查。

检查方法:只读首屏、章节标题和各章第一段,能否说清做什么、为什么现在、主干怎么做、代价和风险,以及要确认什么。说不清,就先改这一层。

信息的形状

分层之后,再决定每块信息怎么呈现。把一段长文字切成几段,还不能解决并列关系和对比关系难找的问题。

内容用什么呈现为什么
结论、前提、待确认的事高亮块或短句先看到判断,再决定是否展开
并列的职责、约束和理由带标签的列表扫标签就知道有哪些要点
多个状态、方案或风险表格同一组属性能横向比较
有先后的操作有序列表操作顺序不埋在句子里
因果与取舍短段落保住为什么,不拆成互不相干的条目

加粗只标关键词,标题只写这一节讲哪块内容。让标题、表头、列表标签和高亮承担不同层次,避免满屏都是重点。

同一内容的对照

以「多端任务执行与验收方案」为例,同一份内容有两种呈现:左边按章节合成大段,右边突出结论,并把并列信息改成列表和表格。

同一技术方案的大段呈现与结构化呈现对照

右侧先给结论和待评审事项,再展开设计边界。并列职责放进列表,状态和条件放进表格,读者不用逐句从长段落里提取。

状态规则更适合用表格。Task 表示同一目标,Run 记录每次成功领取后的执行;等待恢复沿用当前 Run,验收退回后再次领取才新建 Run。

同一组状态规则由长段落改为表格的呈现对照

读这张表时,可以按「当前状态、允许去向、条件」定位:

  • 等待恢复:回到运行中,继续原 Run。
  • 验收退回:回到待办,再次成功领取时创建新 Run。
  • 取消边界:只有草稿、待办和等待可以取消,两个终态没有出边。

事实与判断

技术方案还要让人分清已知和未定。表达流畅,不能把推测变成事实,也不能把建议写成已经批准的决定。

信息写法
现状事实保留来源、时间与适用范围
未验证假设写明前提及不成立时的影响
已作出的决定写清状态、选择理由和接受的代价
待确认事项写清缺什么证据、如何确认

流程图与关系

图要让读者看清谁和谁是什么关系。组成、交接、时序、状态和数据流不同,不能都画成一串同样的方框。

按关系选图

不同关系采用不同图型。下面的总览展示六类图的组织方式,完整文字看对应单图。

架构、工作流、时序、数据流、状态和实体关系的样图总览

图中是用于说明图型的示例。

要看清什么合适的图组织重点
哪些模块组成系统,谁调用谁架构图主链、归属与系统边界
谁负责哪一步,何时交接或分支流程图、泳道图职责、条件、并行与回路
一次场景中消息按什么顺序发生时序图参与者、发送、返回与等待
哪个事件让状态发生变化状态图主路径、等待、退回与终态
数据从哪里来,经过什么转换数据流图来源、变换、存储与消费
实体有哪些字段,彼此什么关系ER 图字段、键和关系基数

选图先问读者要回答什么,再确定主路径、分组、边界和条件。图型多只是能力范围,选得对才有用。

主线与分支

一张图先安排核心解释路径,再把分支和异常放到对应位置。正常流程可以连续阅读,等待与回退需要独立走线,关键条件放在连接处。

泳道尤其适合解释跨角色交接。下图把用户界面、Agent 运行、策略与恢复、工具执行分开,规划、审批、阻断和结果回报各有对应位置。

用泳道、阶段和条件组织工具调用工作流

  • 泳道:帮助定位动作发生在哪个职责范围。
  • 连线:保留真实起点、终点和方向,分支注明触发条件。
  • 回路:说明为什么返回、回到哪里,不用一条长链掩盖重试或等待。

节点名称和正文保持一致。图标题给读者一个明确主题;调用线写动作,数据流线写传递的数据,状态迁移线写触发事件或条件。

状态与顺序

状态图能把一个常见误读直接展示出来:执行结束以后,任务还需要验收,才能进入完成状态。

正常路径、等待恢复、验收退回和取消分别表达的状态图

主线从草稿走到已完成;运行中的等待和恢复放在下方,验收退回放在上方。两个终态明确标识,没有出边。读者沿线就能找到条件,不必脑补一整套状态机。

这张图与前面的状态表讲同一组核心规则:表适合逐项查允许去向,图适合追踪路径和回路。对象名称相同不算重复,有没有新的理解帮助才是判断依据。

配色与密度

颜色用来区分角色和状态。前端、后端、存储可以有固定角色色;成功、等待、失败另有状态含义。后端节点是绿色,不代表它已经执行成功。

  • 视觉重点:主路径和本次变化更突出,普通关系仍然能看清。
  • 标签位置:说明靠近对应的线或对象,不压住箭头、转折和正文。
  • 信息密度:放不下时拆成总览和详图,不靠缩小字号塞进去。
  • 风格一致:共享字体、颜色含义和标题层级,布局按关系变化。

实体关系图需要保留字段、键和基数。把它缩成几张结论卡,会丢掉技术方案真正需要检查的信息。

保留业务域、实体字段、键和基数的实体关系图

图源与修改

图能持续修改,评审意见才能回到具体节点和关系。模块职责、调用方向或条件变了,应当修改图源并重新生成,避免正文更新了,图片还停在旧版本。

保留什么用来做什么
JSON 或已有 Python 修改源改对象、关系、条件和标题
scene 场景数据保存对象与连线的语义、稳定 ID 和布局结果
SVG、PNG贴进文档阅读,按修改源重新生成
自包含 HTML查找、聚焦和查看已登记的真实关系

绘制统一通过 diagram_kit。内部可以用不同布局实现,共享修改源约定、主题、查看器和交付检查。发布到飞书只是最后的承载步骤,不决定图该怎么组织。

使用时保留这些边界:

  • 自动布局:处理几何,作者仍要确定职责、主路径和条件。自由对象保留复杂分区及分区端点,不根据视觉位置补未声明的关系。
  • 可编辑格式:SVG 保留矢量对象与文字,但不等于完整作者源;draw.io 的真实节点与绑定连线目前只对自由对象图支持。
  • 交互:HTML 的查找、聚焦和路径查看不会自动进入飞书正文。

迭代与验证

后续改动对应的是具体使用问题。保留下来的重点,是哪些地方仅靠写作提醒或生成成功还不够。

遇到的问题怎么调整留下的检查方法
技能已经存在,细化流程时仍手写 Mermaid 或从画板摆节点明确服务、模块、调用和事件迁移属于工程关系,扩展入口判据工程图任务能走到统一绘图入口
标题塞整句结论,正文混入对话来源或个人信息补标题、版式与正文检查用 doc_check 定位可枚举问题,再由作者判断内容
不同图型用法和呈现分散将成熟编译器、专用布局和自由对象收进统一入口图型保留自己的语义,共享源、主题与交付
树根改成浅色底,原来的白字没有同步修正主题覆盖后的文字规则,不改节点、层级与字号看实际画面,不能只检查角色声明
组件页通过检查,最终装配或导出却可能改变样式和索引对最终成品重新检查,静态导出先清理临时状态并固化样式以本次生成的源、场景和成品为准

每次交付分别检查文字和图。

检查对象要回答的问题
文字速读层只读正文,是否能说清结论、主干、代价和待确认项
图与正文对象、方向、职责和条件是否一致
实际画面正常阅读尺寸下,文字、主线、分支和箭头是否清楚
修改与导出修改源是否保留,成品是否来自同一版本,格式是否真正支持

自动检查能拦住格式和部分结构问题,读图仍要看实际成品。生成成功、截图存在,都不能单独证明文档已经讲清楚。

使用与边界

使用时,把材料、读者、目标和范围一起给出。更新已有文档,先读全文和图,再改相关结论,不把新增内容直接挂到末尾。

  • 写方案:「基于这些材料写技术方案,给评审会看,重点说明候选、代价和回退。」
  • 改文档:「按这些评审意见改这份方案,保留现有事实、图和有效结论。」
  • 改工程图:「重画这张架构图,保留节点和条件,突出主链,交付可修改源。」

engineering-docs 主导要评审、要确认决定的方案与工程图。技术分享的叙事由分享技能负责;content-infographic 将抽象内容做成便于理解的信息图;好好说话负责最后的中文表达。它们可以配合,借图不接管正文。

有三件事值得直接带回日常文档:

  • 先整理信息的层级,再改句子,完整条件留在能查到的位置。
  • 先判断关系,再选图,不能为了版式整齐改掉真实流程。
  • 保留修改源,检查最终成品,允许明确说明哪项尚未验证。
100%