面向API技术文档作者的Git工作流 - Bump.sh

技术编写人员经常面临如何使API文档与不断变化的API设计保持同步的挑战。本文将探讨这一问题的解决方案，重点介绍如何通过并行开发和自动化工具来简化流程，帮助技术作者更高效地管理API文档。

为API文档使用Git工作流的好处

将Git纳入技术写作工作流程可以带来以下几方面的优势：

• 版本控制：Git工作流能够对所有文档更改进行跟踪和版本管理，方便回滚和历史记录分析。
• 协作提升：Git促进了技术作者与开发团队之间的协作，支持持续的反馈和改进。
• 自动化集成：通过与CI/CD（持续集成/持续交付）管道的结合，能够在API代码库发生更改时自动更新文档。

尽管如此，并没有一种通用的解决方案适用于所有场景。接下来，我们将探讨技术编写人员可能遇到的常见情况，以及如何优化文档流程的工作流选项。

使用代码生成文档的挑战

通过代码注释直接生成OpenAPI文档。然而，这种方法也存在以下问题：

1. 文档过于技术化：生成的文档可能缺乏针对外部消费者的上下文。
2. 文档不完整：由于时间限制，生成的文档可能存在遗漏。
3. 编辑复杂性：技术作者需要直接修改源代码中的注释，这对专注于提高文档质量的技术作者来说是一项挑战。

为了解决这些问题，可以考虑以下改进建议：

将改进的文档合并到源代码中

技术作者可以向工程师提供改进后的文档，由工程师将其合并到源代码中。这种方法虽然效率较低，但可以在不改变现有开发流程的情况下提升文档质量。如果技术作者熟悉Git和代码，也可以直接创建特性分支，并利用CI/CD管道验证更改的正确性。

使用代码注释一次性生成文档

与其依赖代码注释生成文档，不如生成一次OpenAPI规范文档，并将其作为主要的真相来源。这种方式避免了技术作者频繁编辑源代码的需求，同时减少了从零开始编写基于YAML的OpenAPI文档的工作量。生成的OpenAPI文档可以存储在与代码相同或单独的存储库中。

对于绿地API设计，协作是关键

在设计新的（绿地）API时，采用设计API实现的真相来源。

然而，技术作者往往被排除在设计过程之外。实际上，让技术作者参与API设计过程可以带来以下好处：

• 设计输入：技术作者能够从文档的角度提供设计建议，提升清晰性、一致性和可用性。
• 以用户为中心的文档：早期参与有助于确保文档从一开始就满足目标受众的需求。
• 文档与API策略一致：确保文档不仅具有信息性，还能与API计划的整体目标保持一致。

Git工作流冲突：独立存储库的案例

在某些组织中，工程团队的工作流可能与技术作者的工作流产生冲突。例如：

• 技术作者无法及时更新存储在同一Git存储库中的文档，需等待开发周期完成。
• 技术作者的文档更改可能增加开发人员的工作量，导致效率降低。

为了解决这些问题，可以考虑将API文档存储在单独的Git存储库中。这种方法的优势包括：

• 文档管理灵活性：文档可以独立于代码进行更新，方便修订和发布。
• 文档版本控制：专门针对文档的更改历史记录，便于追踪和回滚。
• 跨团队协作：非开发人员（如产品经理）也能更轻松地参与文档工作。

当然，这种方法需要额外创建独立的CI/CD管道来支持API文档的自动构建和发布。此外，需特别注意防止文档与代码不同步的问题。

结论

协调API文档与软件工程是一项持续的挑战。通过采用独立存储库、利用OpenAPI规范和自动化工具，技术作者可以与工程师更高效地协作，提供卓越的API文档体验。这不仅提升了文档质量，还改善了开发者的整体体验，从而推动API项目的成功。

原文链接: https://bump.sh/blog/git-workflows-for-api-technical-writers