文档在软件开发中对于清晰沟通、一致性和知识传承至关重要。它确保团队成员在入职时能够理解代码，减少日常工作中的学习曲线，降低因上下文丢失而产生的错误和重构风险。
文档对非技术相关人员同样重要，如产品经理、客户支持代表，以及市场、销售和运营人员。清晰的文档促进团队间协作，创建唯一可信的数据源，避免沟通误差。随着软件演进，规范文档简化代码库维护和新开发者的入职，增强项目的长期生命力。
对外而言，产品使用说明文档有助于销售和市场推广，减少客户入职难度，提升用户对产品的参与度。为外部利益相关者撰写功能和流程文档，也便于收集他们的反馈以改进产品。
尽管重要，文档往往被忽视。软件工程师通常不喜欢写面向人的文字，因此经常尽可能跳过。但他们几乎总面临截止压力，在不得不妥协时，文档往往是被牺牲的部分。即便撰写了文档，繁重的工作和时间压力也常导致内容仓促或不完整。编写高质量文档需要时间。另有挑战包括把握适当的细节深度，以及随着系统演进保持文档的更新。
在近期基于大模型（LLM）的 AI 浪潮兴起前，AI 工具已帮助生成文本内容多年。诸如 Grammarly 这样的写作工具，帮助找词和纠错，对使用外语写作的人员尤其有益。在软件开发领域，Swagger 和 Javadoc 等工具结合 AI，自动生成与代码更新同步的 API 文档。
本章评测的工具大多于 2022 年以来伴随生成式 AI 浪潮发布，均致力于超越简单模块（如 API）和辅助工具（如 Grammarly）的文档生成，部分甚至希望达到能替代人工撰写文档的水平。
文档类型
软件开发中常见的四种关键文档类型：
- API/SDK 文档
这是开发者的重要资源，提供清晰且结构化的接口、方法和服务说明。API/SDK 文档作为软件组件间的桥梁，确保开发者能够高效集成和使用系统。 - 内部文档及功能规格说明
当业务相关人员定义新产品或功能以实现业务目标时，会编写功能规格说明，告知软件工程师需实现的功能。工程师则需扩展该规格，补充技术系统设计、架构决策和工作流程，记录不仅是什么被实现了，更重要的是如何实现的。此类文档对软件项目的维护和演进至关重要，尤其在原开发者离开后。 - 用户指南和手册
帮助非技术用户了解软件使用方法，涵盖安装指导、故障排查等内容。它们在销售过程中为销售和市场人员提供支持，也在客户使用产品时发挥作用。挑战在于为非技术背景的用户编写易懂的文档。 - 发布说明与变更日志
用于传达软件变更信息，如缺陷修复、新功能或性能提升。有效的发布说明不仅让内部外部利益相关者知晓更新，还提醒他们调整集成和工作流程以适应变更。
评估流程
我评估了超过 20 款文档和技术写作领域的 AI 工具，最终筛选出本章重点介绍的四款。所有涉及的工具均满足以下条件：
- 由专业团队开发维护；
- 生成高质量的结果；
- 提供一定程度的免费功能或试用；
- 截至撰写时（2025 年中）拥有较高的用户采纳率。
此次测试中，我创建了一个非常简单的认证流程，包含前端和后端。完整代码已上传至本书的 GitHub 仓库，包含注册、登录和注销等流程。我使用本章的 AI 工具为我的代码生成文档，主要的对比点是生成的文档是否适用于前面介绍的四种文档使用场景。
同样，在测试中我优先选择了可通过简单注册和免费试用使用的工具，因此避开了企业级工具。
每次测试生成的完整文档均可在本书 GitHub 仓库中查阅。
Swimm
Swimm 是一款专为软件工程师设计的 AI 驱动文档工具，自动化创建和维护代码文档。为了确保文档随每次代码变更保持最新，Swimm 可直接集成至代码仓库。工程师可以为特定代码文件或代码片段创建文档，也可以随着每次拉取请求（PR）创建或更新文档。后一种方式非常契合大多数软件开发团队的流程，因为 PR 代表了对代码库最细粒度的迭代，每次迭代都需被记录，否则可能使现有文档过时。
我认为这一流程与第 3 章介绍的自动代码评审流程类似。将这类工具嵌入仓库能无缝融入现有软件开发流程。
虽然 Swimm 支持集成到仓库中并随每个 PR 自动创建或更新文档，但为了本次对比测试，我并未使用该流程。相反，我仅使用了 Swimm 的浏览器界面，连接仓库、选择需文档化的具体文件，并通过提示生成文档内容，如图 6-1 所示。
在这个流程中，我通过一个简单的提示请求 Swimm 为我的认证流程的后端部分生成文档：
“描述其功能和技术实现。”
期望输出是一份文档，用于内部了解正在进行的项目，以及帮助新成员快速入职。图 6-2 展示了生成结果的示例。
这个输出相当不错。我喜欢这份文档的结构和内容。不过，我的认证流程可能过于简单，无法充分展示 Swimm 的全部潜力。因此，我测试了第二个更复杂的示例：
“描述前端代码并为每个流程创建测试计划。”
结果依然非常好。它生成了一份完整的文档（目录见图 6-3），包括高层次的介绍，以及对影响流程的具体代码组件的深入解析，这些内容都应被详细记录。
文档的最后一部分，正如我所要求的，识别了代码的主要流程并为每个流程提供了测试计划。实际的测试计划相当简单，但这很可能是底层流程简单的结果，示例如下：
测试计划
测试登录流程
- 验证登录表单默认可见。
- 输入有效凭据并提交，期望显示成功消息。
- 输入无效凭据并提交，期望显示错误警告。
- 点击“注册”，确保注册表单出现。
测试注册流程
- 点击“注册”切换到注册表单。
- 输入有效信息并提交，期望显示成功消息。
- 输入无效信息并提交，期望显示错误警告。
- 点击“登录”，确保登录表单重新出现。
测试成功登录及登出
- 成功登录或注册后，验证显示成功消息。
- 点击登出按钮，确保重新显示登录表单。
Swimm 在本次测试中表现良好。使用该工具入门简单，能够根据我的请求生成相关文档，且采用了正确的 Markdown 格式，这也是技术文档的标准格式。不过，我发现 Swimm 目前只能一次为一个代码文件生成文档，这导致生成的文档非常零散，更像是一个 README 文件，而非高层次的代码库及流程文档。
我认为 Swimm 将来扩展处理更大范围的源代码材料是其自然的发展方向。它可以利用其出色的集成流程，为整个代码库或至少一组文件创建文档。可以横向地，通过使用所有前端文件作为文档对象，记录前端代码结构；也可以纵向地，通过使用与某功能相关的所有文件，记录该功能流程。
因此，我给 Swimm 评分为 6 分（满分 10 分）。尽管用户体验不错，但输出的文档质量距离我期望从团队获得的标准仍有较大差距。
ChatGpt
ChatGPT 是大多数软件工程师用来创建文档的首选大语言模型工具，因此我将它纳入本章，特别是使用了撰写时（2025 年中）最先进的 GPT-4o 模型。
我首先让 ChatGPT 生成我的代码文档。提示中包含了所有六个代码文件、一张仓库结构截图（帮助其理解代码文件之间的关系），以及文档应包含的内容说明，如图 6-4 所示。
ChatGPT 生成了非常全面的文档，其目录如图 6-5 所示。
这是一个非常好的输出；文档内容非常完整，涵盖了所有预期的主要部分，从高层次的上下文（如仓库结构）到对每个具体组件的详细深入解析，比如图 6-6 中可见的 API 部分。
你可以让 ChatGPT 直接将文档输出为 Markdown 文件。我已将 ChatGPT 生成的最终文档（以及本章其他工具生成的文档）提交到本书的 GitHub 仓库。
正如预期，ChatGPT 在这个有限范围的测试中表现非常出色。它一次最多处理 20 个文件，且文件大小限制根据文件类型不同而异。对于像我这个认证应用这样的小型项目，这完全足够，但对于大多数生产级应用则不够用。此外，与能直接连接代码仓库的工具相比，ChatGPT 的用户界面较为不便。需要手动上传文件并向 ChatGPT 提供文件结构和相互关系的上下文信息，这使得在处理大型项目时使用起来更具挑战性。
因此，我给 ChatGPT 在该用例中的评分为 7 分（满分 10 分）。文档质量非常好，但受限于上述限制和不便的界面。软件工程师要在每份文档最多支持 20 个文件的限制内，有创意地为应用的各个功能集群（按功能、技术栈部分或模块）编写文档。
Cursor
Cursor 是 AI 编码工具领域的新秀，2023 年发布，在具备 AI 代码助手能力的 IDE 细分市场迅速占据大量份额，该市场由 GitHub Copilot 领导。截至 2024 年 8 月，Cursor 拥有 4 万客户。
Cursor 是一款以 AI 为核心的 IDE，起源于流行的 Visual Studio Code 分支。它允许软件工程师选择驱动工具的 LLM；我使用的是 Anthropic 的 Claude 3.5 Sonnet。作为真正的 IDE，Cursor 能够访问我代码仓库中的所有代码文件，无论数量和大小。你可以通过聊天功能输入提示，如图 6-7 所示。
Cursor 生成的文档很好，包含了预期的主要组件部分，目录如图 6-8 所示。
尽管大纲非常全面且内容相关性强，但 Cursor 在生成 Markdown 文档时存在一个重大缺陷。由于某种原因（可能是程序错误），生成的内容只有部分被格式化为 Markdown 文件，有些部分以纯文本形式输出，比如图 6-9 中的代码片段，这使得文档的可读性大大降低。
尽管存在格式问题，Cursor 生成的文档内容丰富，涵盖了正确的主题，并且技术深度恰当，完全符合我对团队可接受文档的标准。因此，我给 Cursor 评分 8 分（满分 10 分）。
Scribe
Scribe 是本章中评测的工具里非常不同的一款。它更适合以可视化方式创建用户指南、标准操作流程（SOP）或错误报告。与我使用 Swimm、ChatGPT 和 Cursor 主要聚焦于撰写某个产品或功能的技术实现文档不同，我用 Scribe 生成了关于产品功能的使用指南。
虽然 Scribe 最初于 2019 年作为一个基本的屏幕录制工具发布，但我本次测试用到的功能，名为 Scribe AI，是在 2023 年推出的。它基于原有功能，允许用户录制浏览器操作过程，但不只是保存视频，而是基于录制中的屏幕切换，自动生成带注释的完整工作流程。因此，它更适合 UI 相关的应用场景，如错误报告和产品使用指南。
测试开始时，我安装了 Scribe 的 Chrome 插件，用它录制了一段简单的会话——新账号注册并登录。我的目标是让 Scribe 生成一份用户指南，供外部非技术利益相关者（如产品用户）使用和分享。
第一次录制体验非常顺畅，第一次尝试就顺利获得所需录制内容。这个录制结果被称为“Scribe”，既指视频录制本身，也指生成的带注释的工作流程，已公开发布（可通过公共链接访问）。我认为这个输出不错，因为它识别了工作流程中的屏幕切换，捕捉了每个屏幕的截图，并高亮显示了用户在屏幕上的操作，引发了屏幕的切换。结果与用户观察工具如 Hotjar 或 Fullstory 类似，这些工具常用于用户调研和错误追踪。
Scribe 还提供了一个功能，能将上述公共链接中的原始 HTML 文档转换成 AI 生成的文档。我用认证流程测试了这一功能，用户可输入提示，指定从屏幕录制中生成的文档内容。我给出的指令很简单，如图 6-10 所示。
生成的文档可通过此链接公开访问。但我觉得这个输出令人失望。内容过于通用，感觉像是适用于任何应用，而非专门针对我的项目。它生成了一份文档，并将多个“Scribe”（具体流程）嵌入其中，而非基于我录制的流程来生成文档，这才是我的初衷。这让我觉得该工具更适合生成包含多个不同 Scribe 合并的大型文档（例如产品指南）。生成文档的内容与本次用例关联不大。因此，我给 Scribe 评分 5 分（满分 10 分）。
工具对比
表 6-1 比较了本章讨论的各工具评分。
| 工具 | 用户体验 | 测试表现 |
|---|---|---|
| Swimm | 仓库扩展 | 6/10 |
| ChatGPT | 网站 | 7/10 |
| Cursor | IDE | 8/10 |
| Scribe | Chrome 扩展 | 5/10 |
总结
作为一名 CTO 超过十年，我发现文档总是缺失严重，但从未严重到值得暂停正在进行的工作去修复的地步。事实上，糟糕的文档是一种技术债务，但它不会破坏系统或降低性能，反而影响的是团队的工作效率。这种债务更隐蔽，或许对软件开发团队的伤害更大。
我一直很难推动团队里的软件工程师去编写文档，更难保持文档的组织性、可访问性和及时更新。我认为本章评测的 AI 工具能够在这方面发挥基础性作用。通过简单的提示，它们能在几秒钟内生成文档，而人类至少需要一两个小时。随着系统复杂度增加，文档编写和维护的难度和时间成本也会成倍增长。对于几十人的团队来说，这项工作每年轻松积累成数千小时。
虽然 AI 工具能即时生成文档，但它们也可能生成糟糕的文档（就像人类一样）。我建议团队对文档的处理应像制定编码规范一样，创建提示模板甚至文档模板，预先定义章节和子章节。这有助于避免文档冗长，并通过提高内容查找的便利性来提升可读性。
最后强调一点，AI 工具生成的文档必须由团队成员仔细审核和编辑。虽然生成 90% 的内容只需几秒，但最终的修订和质量把控必须由人完成，因为输出不一定能完全满足目标需求。以 Scribe 为例，生成的文档过于通用，只有人工审查者才能发现缺陷并手动改进文档。
