生成式AI在软件开发中的应用

第 6 章 文档和技术写作 文档和技术写作

本作品已使用人工智能进行翻译。欢迎您提供反馈和意见：[e-mail]

文档对于软件开发的清晰度、一致性和知识传递至关重要。它能确保团队成员在入职时就能理解代码，并减少日常工作中的学习曲线，从而减少丢失上下文以及随之而来的错误和重构。

对于非技术利益相关者（如产品经理、客户支持代表以及市场营销、销售和运营人员）来说，文档也是重要的。清晰的文档可以促进团队间的协作，并创建一个单一的真相来源，从而防止误传。随着软件的发展，适当的文档可以简化代码库的维护和新开发人员的入职，从而延长项目的寿命。

在公司外部，记录软件产品的使用方法可以帮助销售和营销工作，防止客户入职过程中出现困难，并促进用户对产品的参与。为外部利益相关者编写功能和工作流程也是收集他们对如何改进产品的反馈意见的一个很好的起点。

尽管文档很重要，但它往往根本不会被写出来。软件工程师通常不喜欢为人撰写文档，所以他们经常能不写就不写。但他们几乎总是面临着截止日期的压力，当他们不得不做出妥协时，文档往往就会被抛在脑后。即使写好了，繁重的工作量和时间压力也往往导致内容仓促或不完整。编写高质量的文档需要时间。其他的挑战还包括找到正确的详细程度，以及随着系统的发展不断更新文档。

在最近LLM驱动的人工智能浪潮之前，人工智能工具已经帮助生成书面内容很多年了。像 Grammarly 这样的写作工具可以帮助找到正确的单词并修正错误，对于用外语写作的人尤其有帮助。在软件开发中，Swagger 和 Javadoc 等工具也利用人工智能，在代码更新的同时自动生成 API 文档。

我在本章中回顾的工具都是最近推出的，大多是在 2022 年人工智能生成浪潮兴起之后推出的，它们都旨在将从代码生成文档的简单性扩展到简单模块（如 API）和辅助工具（如 Grammarly）之外。有些人工智能的目标是足以取代人类编写文档的需要。

文档类型

软件开发中常见的文档有四种主要类型：

API/SDK 文档

对于开发人员来说，API 和软件开发工具包 (SDK) 的文档是一个重要的资源，它提供了关于软件系统内可用功能、方法和服务的清晰、结构化的详细信息。这些文档接口是连接不同软件组件的桥梁，可确保开发人员高效地集成和使用系统。

内部文档和功能说明

当业务利益相关者定义了要开发的新产品或功能，以实现业务目标时，他们会编写功能规范，让软件工程师知道要实现哪些功能。工程师的职责是通过技术系统设计、架构决策和工作流程来扩展这些规范，不仅要记录实现了哪些功能，还要记录如何实现这些功能。这类文档对于长期维护和发展软件项目至关重要，尤其是当最初的工程师不在时。

用户指南和手册

这些文档有助于非技术用户了解如何使用软件。它们包括从安装说明到故障排除技巧的一切。在销售过程中，这些文档可以作为销售和营销同事的支持材料，在客户使用产品时也非常有用。这里的挑战在于为没有技术背景的用户编写文档。

发行说明和更新日志

这些文档用于沟通软件的变更，如错误修复、新功能或性能改进。有效的发布说明不仅要让每个人都了解情况，还要告知内部和外部利益相关者需要更新集成和工作流程以适应变化。

评估过程

我对文档和技术写作领域的 20 多款人工智能工具进行了评估，以便筛选出本章重点介绍的四款工具。这里涉及的每个工具都符合以下标准：

• 这是一个专业的项目，背后有一支能干的团队。

• 它能产生高质量的结果。

• 提供一定程度的免费或试用功能。

• 在撰写本报告时（2025 ...