OmniDoc技术文档图解怎么做：用 Markdown 画流程图与架构图
讲清在 Markdown 技术文档里加入流程图和架构图的做法，包括动手前的判断、在 UniDoc 网页编辑器里的操作步骤，以及成稿后的核对方法，适合需要写接口文档、设计说明和部署说明的开发者与技术写作者。
技术文档里，一段文字很难说清“请求经过哪些服务、数据从哪里流向哪里”。流程图和架构图能把这些关系直接摆出来。很多团队的接口文档、设计说明和部署手册都用 Markdown 编写，图却常常靠截图插入，之后一改就得重画。
这篇文章写给需要在 Markdown 技术文档里加入流程图和架构图的开发者、技术负责人和技术写作者。读完后，你会知道动手前该判断什么，如何在 UniDoc 网页编辑器（app.unidoc.top）里按步骤画图，以及成稿后怎样核对。
这里讲的是通用做法，图的具体语法以编辑器实际支持的写法为准，操作前请先用小例子验证。
在 Markdown 文档里画流程图和架构图，怎么选做法？一句话结论：结构简单的用文本描述，结构复杂的先出草图再落地
先用一句话给出判断：流程只有几步、关系清楚的，直接用文本描述节点和连线；模块多、层级深的架构图，先画草图定好结构，再写进 Markdown。下面的表格可以帮你快速对号入座。
| 你的情况 | 推荐做法 | 原因 |
|---|---|---|
| 业务流程或审批流程，步骤不超过十来个 | 用文本写节点和连线，直接放在文档里 | 改一个节点只需改一行，版本对比清楚 |
| 系统架构图，模块多、有上下层关系 | 先在草稿上定好模块和边界，再用文本分层描述 | 结构先清楚，文字实现时不容易漏掉依赖 |
| 图需要频繁改动，且和代码一起维护 | 图以文本形式存进仓库，与文档一起提交 | 图和正文同步修改，不会出现图已过时的情况 |
| 图样式要求很高，如印刷级配图 | 用通用绘图软件画好，导出后插入 | 排版与配色的自由度更高 |
| 只需要一次性说明，不会再改 | 截图插入即可 | 省时间，但之后更新要重新截图 |
开始之前：先确认这几点
先想清楚这张图要回答什么问题。 一张图只回答一个问题，比如“订单从下单到出库经过哪些环节”，比把所有细节塞进一张图更容易读懂。问题越具体，节点就越好选。
确认读者会怎样使用这张图。 如果读者要照着图排查问题，节点名称应与代码、日志里的名字一致；如果读者只是想了解大致结构，图可以概括，细节放到正文里。
准备好节点清单。 动手前把模块或步骤名称列成清单，标出谁调用谁、数据往哪里走。清单写完再落笔，能避免在编辑器里边画边改。
决定图和正文的分工。 图负责展示关系，正文负责解释条件和异常情况。如果一张图里同时塞了关系和规则，读者很容易漏看其中一半。
确认文档将来的输出形式。 如果稿件还要转成 Word 或 LaTeX 给他人审阅，需要提前留意图的表示方式，之后再统一检查。
在 UniDoc 网页编辑器里画流程图的步骤
- 打开 app.unidoc.top，新建一份 Markdown 文档，并写好标题和前言，让文档结构先立起来。
- 在正文中找到需要放图的位置，把节点清单按顺序列出，每个节点用一个简短、与代码一致的名称。
- 先写一个只有两三个节点的小例子，检查编辑器能否正确渲染，以及箭头的方向是否符合预期。
- 确认小例子没问题后，按流程顺序补全节点和连线；分支流程要把判断条件写在连线上，便于读者理解。
- 架构图按层次分段书写，先写外层的模块，再逐层展开，每层的说明紧跟在图后面。
- 图写完后，在正文中用一两句话解释图的关键路径，不要让读者只能靠猜来理解图的含义。
- 文档完成后，切换到预览或导出结果，逐张图检查渲染是否完整，再进入下一节的核对。
做完后逐项核对
| 检查项 | 怎么看 | 有问题怎么办 |
|---|---|---|
| 节点名称 | 与代码、接口名或配置项逐一对照 | 统一改成代码中的标准名称，并在正文里注明对应关系 |
| 箭头方向 | 沿着箭头从起点走一遍，看是否与业务逻辑相符 | 检查调用方和被调用方是否写反，修正后再走一遍 |
| 分支与异常路径 | 确认每个判断节点都有“是”和“否”两个出口 | 补上缺失的分支，或在正文中说明为何省略 |
| 图文一致 | 对照正文描述，看图中是否有正文没提到的模块 | 补充正文说明，或删除图中多余的节点 |
| 渲染与导出 | 预览或导出后，看图是否完整、文字是否错位 | 检查语法，缩短过长的节点名称，再重新导出 |
| 错别字与专有名词 | 逐个通读节点文字 | 用全文搜索检查同一名词的写法是否统一 |
机器辅助写出的图和文字都需要人工核对，尤其是涉及权限、金额和数据流向的部分，不能只看渲染效果就认为无误。
📊 核心对比
文档里插入图示，常见的有三种做法，各自的适用场景和局限如下。
| 做法 | 适合场景 | 主要局限 |
|---|---|---|
| 文本画图 | 图需要经常修改，且与代码、文档一起版本管理；流程和模块关系清楚 | 复杂排版受限，需要学习一点语法 |
| 插入截图 | 只需一次性说明，不会再改，要求快速完成 | 每次修改都要重新绘制、重新截图，容易与正文脱节 |
| 通用绘图软件导出后插入 | 对外发布的正式材料，对配色和布局有较高要求 | 图与文档分离，更新时需要两边同步 |
❓ 常见问题（FAQ）
1. 技术文档图解方法里，文本画图和截图哪个更好？
没有绝对更好的做法。图经常要改、需要和代码一起维护时，文本画图更合适；图只说明一次、不会再动时，截图更省事。
2. 图画好以后能导出成 Word 吗？
UniDoc 网页编辑器支持与 Word、LaTeX 之间的往返转换，也支持无损的 HTML 导出。导出后请逐张检查图是否完整、文字位置是否正常。
3. 图里的中文显示错乱怎么办？
先检查节点名称中是否含有特殊符号，再缩短过长的文字。如果在另一个工具里打开时仍然错乱，换用纯文字的节点名称重新导出，并在正文里补充说明。
4. 图太大，读者看不清怎么办？
把架构图拆成多张，每张只展示一层或一个子系统，并在图后用一句话说明它与上一层的关系。节点过多时，也可以把次要模块合并成一个节点。
5. 文档分享给别人后，怎样确保对方看到的是新版？
使用编辑器的分享链接时，请在发出前再核对一次图和正文是否已经同步。分享后如果有修改，应同时通知对方重新查看。
📝 总结
在 Markdown 技术文档里画流程图和架构图，关键是先定结构、再落笔，并在成稿后逐项核对节点、箭头与正文是否一致。在 app.unidoc.top 中按上面的步骤操作，可以让图与文档一起编写、一起更新。
