每个产品，都会有自己的文档。即使你的产品是一个交互设计非常简洁直观的 C 端产品，仍然会包含一些需要解释更多、但又不好在产品界面上呈现增加复杂度的地方。因此，文档的管理、维护与发布是每个产品都需要重视的事情。
一般搭建产品文档，大家会采用飞书文档、语雀、Notion 等开箱即用的文档工具，也可能使用 Confluence、CMS 等内容管理工具，或者使用 Docusaurus、Gitbook 等文档生成器，多多少少会遇到以下的一些问题：
- 文档要通过代码方式来编写，成本高。文档写出来了之后实际阅读的效果还是偏差的；
- 文档涉及到多个角色进行协同制作，版本管理难做、不好传递优化建议点给对方；
- 将制作好的文档发布到正式环境过于简单或复杂，可能涉及到工程化，非技术同事难以上手，容易弄错。
Apifox 团队之前是使用 Docusaurus 来制作我们的文档的。随着文档的持续迭代，我们也碰到了上面的一些问题。我们将经验与教训总结后，将解决方案开发到了 Apifox 中。于是现在，Apifox 团队的产品文档已完全迁入了 Apifox 中，由 Apifox 进行制作与呈现。
我将分享我们如何通过 Apifox 来搭建产品文档的实践。在这之前，如果你想再细瞅一眼 Apifox 产品文档的具体效果，也可以通过 Apifox 帮助文档进行查看，欢迎拍砖。
背景
在开始介绍我们的实践之前，有一些上下文可能需要首先说明，这样才会让大家更好的理解我们为何要这样去做。我们公司的产品文档，总的来说是产品 与运营部门同事协同制作的。主要的流程如下所示：
以上流程是无需技术人员参与的，所有产品文档相关操作均由这两个部门的同事完成。接下来我将依照此流程来解释具体如何通过 Apifox 完成搭建产品文档任务的。
核心流程
1. 创建一个迭代分支来进行内容的管理与协同
某个研发迭代开始后，会由运营同学在 Apifox 中创建一个迭代分支，来将当前迭代中全部涉及改动的文档都放在此分支中进行协同，避免改动直接影响主分支。
创建完成后，产品经理根据迭代实际更新的功能，将已存在但需修改的文档导入此迭代分支，新功能要写新文档的在迭代分支中进行创建。这里的操作跟 API 文档的迭代分支使用用法完全一致。
因为对主分支设置了保护，所以不允许直接在主分支中更改文档内容。这代表不可以直接手动修改用户可见的发布文档中的内容，让产品文档更稳定、减少随意更改导致改错内容并被用户看到的情况发生。
2. 使用精美的 MD 编辑器编写每一篇文档
产品经理会在迭代分支中，使用 Markdown 编写当前迭代需要更新的文档。Apifox 中的 Markdown 功能非常强大，有着各种可视化组件点击即可插入很多复杂样式，上手门槛较低，能够不用多花精力轻松编写出一份精美的文章。
除了一般的 MD 样式可视化插入之外，Apifox 额外增加了以下特色功能：
- 插入项目内接口/文档，让各篇文档能够链接起来形成引用链，可以无缝跳转，提供读者更丝滑的体验，更好的解决读者的需求与问题，是个非常重要的功能。
- 提供丰富的资源插入功能，如 Icon、高亮块、表格、步骤、Mermaid、视频等 ，不用费心再自己去找资源、学 MD 样式语法，才能让文档变得更加好看。
3. 产品/运营同事协同打磨文档
产品经理在迭代分支中写完文档的初版后，为了让文档的质量更好、清晰直观、能够帮助到用户，会将文档交付给运营同事，让其站在用户的角度进行阅读并提出修改建议，进行打磨。
这是原来最费时费力的一个环节，需要两边互相协同，由一方说明自己的想法，并且针对部分地方提出具体的修改建议；再由另一方收悉、理解并实际动手修改。来回过程中经常有会错意、改错内容、文档版本内容差异等等各种问题，导致效率很低。
现在使用 Apifox，两边可直接在文档上进行修改，修改了有实时消息通知推送到 IM 中，其他人可以立即进入文档并轻松看到具体改动，协同效率大大提升。以下是具体步骤：
- 产品经理创建了文档初版，运营人员看到了通知后进入阅读文档，将想要修改的内容直接在此文档中进行修改。
- 修改保存自动触发通知，会在已设置好的 IM 群上发送改动消息卡片，群内成员看到改动概览消息卡片后，可以点击通知链接一键进入相关文档。
- 通过修改历史，对比差异，选择当前版本和原版本，来轻松查看对方修改内容，并决定如何调整文档。可以选择不接受建议还原回原有版本，也可以接受修改并保持最新版本。
产品、运营两边重复上述步骤，直到文档内容打磨完成，确定了一个大家都认可的版本。
4. 正式发布文档内容前的准备与审核
为了确保文档中的内容与产品截图与用户可以用到的完全一致，我们均推荐在产品的正式环境上，来进行截图。这样同时可以验证一遍上线的新能力在正式环境中是否异常。运营人员在线上使用新功能并进行截图后，添加入文章中。
运营确认本次迭代中的已制作好内容的文档，选中并提交 MR 申请合入主分支。
运营经理或其他项目管理员审核要发布的文档内容，再次确认无误后即可选择合并入主分支。
合并完成，用户访问发布文档时即可看到合并入主分支的最新内容了。
其它优点
除了已介绍的能力之外，在发布文档方面 Apifox 还有以下的功能帮助大家搭建更符合自己需求的产品文档站。
1. 进行符合产品/公司风格的整文档站样式设置
可以设置发布出去的文档站的整体样式，让整个网站的风格更贴合你们公司的调性，以及加上更多的相关资源和公司内容链接，让用户有更好的体验。
Apifox 的帮助文档即设置了自己的 logo，以及一些 Apifox 相关资源的链接。左上包含了公司 logo，右上包含了各种公司相关的资源链接，把开发者更关心的开放 API 文档也设置在了产品文档内：
2. 零运维发布体验
在 Apifox 中，只需要在发布文档功能中，点击"发布"按钮，即可一键将整个文档发布到互联网中供你的用户进行阅读，Apifox 官方提供了域名可供大家使用。节省掉许多的运维工作。
当然，如果你需要让文档更加像自己公司的网站，我们也提供了自定义域名功能，让你能用自己公司的域名来访问文档。
以及简单操作就可以在已发布的产品文档站点中支持普通搜索、Algolia 全文搜索，接入 GA、设置重定向等各种高级能力。这些配置都不太需要操作者有足够的工程能力，按照界面引导和帮助文档即可轻松设置。
3. 对 SEO 更友好的多种设置
Apifox 会根据一些基本设置，帮助已经发布出去的文档站自动生成合理的 Slug，用来更好的让用户进行访问与传播。
当然如果对于 SEO 有更高级的需求，也同样支持针对每一篇文档进行自定义 Slug、Meta Data 等各种内容的设置。
结语
以上就是通过使用 Apifox 来进行产品文档维护的具体实践。
除了以上提及的内容之外，我们也可以把产品帮助文档、开发者文档与 API 文档以一个风格进行维护并全部串联到一起，这样给你的用户的体验提升就更好了。如果你的实际情况比较适合，欢迎你参考此实践试试看，也可以推荐给其他小伙伴使用。期望能够为你的产品文档搭建工作带来一些效率、质量上的提升。