本文主要讨论的是文档自动化的实现建议，包括：

·         直接从源代码注释中，生成可读的文档材料；

·         将系统文档/设计文档等当作源代码管理，使得信息版本化。

·         使用单元测试文档的理念，确保公司各个部门之间文档的标准化。

本文是翻译过来的，有些不太好阅读之处，还请大家海涵。谢先~

引言

通常情况下，正式的文档（如源代码文档、系统需求与设计文档，或者各类用户文档）会被开发团队忽视得彻彻底底，而 DevOps 中关于流程与文档的理念可以帮助缓解这个问题。软件文档通常分为以下几类：代码，需求，设计、系统与用户文档。

文档经常会被忽略的原因之一在于，如果不能与所依赖的开发工具（如版本控制、问题追踪工具、wiki 及源代码）相匹配，标准文档工具及流程反而会对开发团队造成妨碍，并拖慢开发速度①。

本文探讨了文档化所遇到的3个主要挑战：流程、注释源代码以及系统文档；同时解释了以 DevOps 为基础的文档，可以通过怎样的方式使所有相关人等获利，即访问通用、可信的信息源，并查看项目的细节。

问题流程

创建、维护用户文档与系统文档时，操作人员通常会使用笨重的二进制文档（比如 *.docx）。一般来说，在文档协作体系中，还包括一长串来来回回的电邮，或者网络共享的文件，人们使用这些形式相互传送文档的更新版本。

此外，专用格式（ *.docx 与生成的 PDF）往往会因为跨系统操作而产生不一致，从而在跨团队合作时，常常因为工作环境不同而产生数据损毁。

将二进制文件存储在版本控制系统中是一种解决办法，但管理多个版本的二进制文件仍旧极具挑战。采用自动化文档，并将它们集成在软件开发生命周期（SDLC）中同样存在许多问题：

随着项目的进程，这些文档经常会更新地越来越少，或者被完全废弃。

文档数量非常之多，也是不恰当的。或者说，每支团队都应当在丰富与简单之间找到平衡。

文档代码“不分家”

在谈及文档这个话题时，区分客观信息与主观加工过的材料非常重要：

信息指的是数据或者记录的来源；而主观材料则是通过有序地组织信息而产生的可用终端产品，这种信息是可以被读者阅读的，可能包括系统需求文档、设计文档、状态报告等等。

信息可以在不同的源中维护，比如在问题追踪器、wiki 以及代码储存库中；同时，信息应当存储在实际中人们与数据交互或执行的地方。比如在寻找描述某个具体功能的文档时，该文档应就应该存储在相关功能所在之处：代码旁。

如果功能文档没有与代码存在一起，一旦功能有所改变，那么工程师不止需要更新代码，还要寻找代码相关的文档以便更新。文档匮乏会拖慢开发的进度，工程师需要维护、管理并利用好这些信息。

在所有信息存好之后，我们就可以通过工具来撰写大家能够阅读并理解的文档，来为读者提供信息：

这些撰写的材料一旦生成，就不再更改，以作参考信息；生成文档的流程是获取最新数据的方法。将文档材料作为网页上传是保存这类文档的一个完美手段，因为网页显示的总是最新版本的文档。

源代码

长期以来，注释代码的能力都属于编程高级实践的一部分。在过去十年间，人们为了改进文档体验，为各种语言开发了不少工具。这些工具允许开发者将相关信息归档，协助开发人员理解代码。

下面提到的一些工具也允许程序员在自己的文档中将测试以可读的方式添加进去。这样，很拽的地方在于：

·         编译代码时，文档中的测试会自动运行，如果程序员修改了代码，却没有更新文档的话，build 就会失败。

持续集成环境②的快速反馈可以协助程序员，确保其遵守正确的文档策略。

下面的工具是样板库，可以直接从源代码注释中生成可读的文档材料。

·         Ruby: RDoc③

·         Python: Sphinx④

·         Java: Javadoc⑤

·         Ruby, Java, .NET, Flex: Cucumber⑥

·         C++等: Doxygen⑦

通常管理者可能都不清楚应该对工程师要求什么样的文档。笔者就不止一次收到过这样的需求——将每一行代码的功能写在注释里⑧。

管理者需要了解：这类文档对程序员来说任务繁重，很快就能摧毁任何程序员在合理的时间内交付有商业价值内容的能力。

而在 DevOps 中，一切都应该被自动化⑨，并找出可理解与简单化之间的平衡点。

建议：坚持「新对象应该进行文档描述」这个思想，以将所有新对象“自动文档化”，这可能是帮助程序员在代码中添加注释的好办法。

但是，如果没有文档也没什么影响的话（比如引起 build 失败），你会发现一切对象都处在未归档的情况下（或者用占位符信息错误归档），从而导致返工，需要重新整理欠下的⑩一大堆文档。

开发人员可以使用上面列出的工具来验证文档是否过期，从实践效果来看也很不错。

如果想在一个生命周期的结尾对该项目进行记录的话，应当在重要环节将工具打开。从项目一开始，在编写文档时着眼于每一个最小可用的产品⑪：记录实际情况，而不是得出解决方案的过程。

系统、设计和用户文档

撰写系统、设计与用户文档的工具，往往没有注释源代码的工具那样种类丰富。很多时候，公司需要从头开发自己的通用流程与基础架构。

在近期的一篇博文⑫中，Red Hat 的高级技术文档撰写者Mikey Ariel⑬倡导使用持续集成与单元测试文档：

在该文中，Ariel 将这一过程描述为：能够测试文档是否遵守指南（比如，公司使用的是 backend 还是 back-end）以及语法（利用接口使用像是Hemingway⑭或After the Deadline⑮之类的工具）。

使用单元测试文档的理念可以确保公司各个部门之间文档的标准化。

在 DevOpsDays NYC2015 关于文档的讨论中，来自 Etsy⑯ 的 Mike Rembestsy⑰ 将他们的流程描述为「对数据中心的网络基础结构进行动态记录」：

Etsy 使用 Chef 来更新他们的基础结构，同时 Chef 脚本动态地更新Nagios⑱，监视实例与动态编辑、发布网络图。

通过在文档中使用 DevOps 的手段，Etsy 的工程师实现了更新文档的过程自动化，这样在他们完成工作的时候顺便就完成了这一过程。这些理念与实践在保证文档精准的同时，也反映了系统的当前状态。

我们的建议是：将文档当作源代码管理，使得信息版本化，并允许个人有能力维护或将较小的数据来源与各类文档材料自动合并。

处理可控数据可以通过有效利用安排，将降低上下文切换所带来的不利影响⑲。

切换到 DevOps 文档流程与工作流程时，需要转换思想，考虑什么工具对生成文档最为必要。团队在信息生成时越自动化，或者在促进信息管理时越有效，文档的质量与可用性也就越高。

最终，以 DevOps 为基础的文档就能够允许所有利益相关者访问一份通用、可信的信息源，来了解项目详情了。

① essays/agileDocumentationBestPractices.htm
② post.cfm/continuous-integration-in-devops
③ [/url]
④ [url]
⑤ technetwork/articles/java/index-jsp-135444.html
⑥ [/url]
⑦ [url]wiki/Doxygen
⑧ questions/106202/my-boss-wants-a-narrated-line-by-line-english-explanation-of-our-code
⑨ post.cfm/generalized-model-automated-devops-153
⑩ post.cfm/field-study-technical-debt-208
⑪ minimum-viable-product/
⑫ business/15/7/documentation-devops
⑬ thatdocslady
⑭ [/url]
⑮ [url]
⑯ [/url]
⑰ [url]mrembetsy
⑱ [/url]
⑲ [url]post.cfm/addressing-detrimental-effects-context-switching-devops-064

（王鹏高浩淼原创）

本文主要讨论的是文档自动化的实现建议，包括：

·         直接从源代码注释中，生成可读的文档材料；

·         将系统文档/设计文档等当作源代码管理，使得信息版本化。

·         使用单元测试文档的理念，确保公司各个部门之间文档的标准化。

本文是翻译过来的，有些不太好阅读之处，还请大家海涵。谢先~

引言

通常情况下，正式的文档（如源代码文档、系统需求与设计文档，或者各类用户文档）会被开发团队忽视得彻彻底底，而 DevOps 中关于流程与文档的理念可以帮助缓解这个问题。软件文档通常分为以下几类：代码，需求，设计、系统与用户文档。

文档经常会被忽略的原因之一在于，如果不能与所依赖的开发工具（如版本控制、问题追踪工具、wiki 及源代码）相匹配，标准文档工具及流程反而会对开发团队造成妨碍，并拖慢开发速度①。

本文探讨了文档化所遇到的3个主要挑战：流程、注释源代码以及系统文档；同时解释了以 DevOps 为基础的文档，可以通过怎样的方式使所有相关人等获利，即访问通用、可信的信息源，并查看项目的细节。

问题流程

创建、维护用户文档与系统文档时，操作人员通常会使用笨重的二进制文档（比如 *.docx）。一般来说，在文档协作体系中，还包括一长串来来回回的电邮，或者网络共享的文件，人们使用这些形式相互传送文档的更新版本。

此外，专用格式（ *.docx 与生成的 PDF）往往会因为跨系统操作而产生不一致，从而在跨团队合作时，常常因为工作环境不同而产生数据损毁。

将二进制文件存储在版本控制系统中是一种解决办法，但管理多个版本的二进制文件仍旧极具挑战。采用自动化文档，并将它们集成在软件开发生命周期（SDLC）中同样存在许多问题：

随着项目的进程，这些文档经常会更新地越来越少，或者被完全废弃。

文档数量非常之多，也是不恰当的。或者说，每支团队都应当在丰富与简单之间找到平衡。

文档代码“不分家”

在谈及文档这个话题时，区分客观信息与主观加工过的材料非常重要：

信息指的是数据或者记录的来源；而主观材料则是通过有序地组织信息而产生的可用终端产品，这种信息是可以被读者阅读的，可能包括系统需求文档、设计文档、状态报告等等。

信息可以在不同的源中维护，比如在问题追踪器、wiki 以及代码储存库中；同时，信息应当存储在实际中人们与数据交互或执行的地方。比如在寻找描述某个具体功能的文档时，该文档应就应该存储在相关功能所在之处：代码旁。

如果功能文档没有与代码存在一起，一旦功能有所改变，那么工程师不止需要更新代码，还要寻找代码相关的文档以便更新。文档匮乏会拖慢开发的进度，工程师需要维护、管理并利用好这些信息。

在所有信息存好之后，我们就可以通过工具来撰写大家能够阅读并理解的文档，来为读者提供信息：

这些撰写的材料一旦生成，就不再更改，以作参考信息；生成文档的流程是获取最新数据的方法。将文档材料作为网页上传是保存这类文档的一个完美手段，因为网页显示的总是最新版本的文档。

源代码

长期以来，注释代码的能力都属于编程高级实践的一部分。在过去十年间，人们为了改进文档体验，为各种语言开发了不少工具。这些工具允许开发者将相关信息归档，协助开发人员理解代码。

下面提到的一些工具也允许程序员在自己的文档中将测试以可读的方式添加进去。这样，很拽的地方在于：

·         编译代码时，文档中的测试会自动运行，如果程序员修改了代码，却没有更新文档的话，build 就会失败。

持续集成环境②的快速反馈可以协助程序员，确保其遵守正确的文档策略。

下面的工具是样板库，可以直接从源代码注释中生成可读的文档材料。

·         Ruby: RDoc③

·         Python: Sphinx④

·         Java: Javadoc⑤

·         Ruby, Java, .NET, Flex: Cucumber⑥

·         C++等: Doxygen⑦

通常管理者可能都不清楚应该对工程师要求什么样的文档。笔者就不止一次收到过这样的需求——将每一行代码的功能写在注释里⑧。

管理者需要了解：这类文档对程序员来说任务繁重，很快就能摧毁任何程序员在合理的时间内交付有商业价值内容的能力。

而在 DevOps 中，一切都应该被自动化⑨，并找出可理解与简单化之间的平衡点。

建议：坚持「新对象应该进行文档描述」这个思想，以将所有新对象“自动文档化”，这可能是帮助程序员在代码中添加注释的好办法。

但是，如果没有文档也没什么影响的话（比如引起 build 失败），你会发现一切对象都处在未归档的情况下（或者用占位符信息错误归档），从而导致返工，需要重新整理欠下的⑩一大堆文档。

开发人员可以使用上面列出的工具来验证文档是否过期，从实践效果来看也很不错。

如果想在一个生命周期的结尾对该项目进行记录的话，应当在重要环节将工具打开。从项目一开始，在编写文档时着眼于每一个最小可用的产品⑪：记录实际情况，而不是得出解决方案的过程。

系统、设计和用户文档

撰写系统、设计与用户文档的工具，往往没有注释源代码的工具那样种类丰富。很多时候，公司需要从头开发自己的通用流程与基础架构。

在近期的一篇博文⑫中，Red Hat 的高级技术文档撰写者Mikey Ariel⑬倡导使用持续集成与单元测试文档：

在该文中，Ariel 将这一过程描述为：能够测试文档是否遵守指南（比如，公司使用的是 backend 还是 back-end）以及语法（利用接口使用像是Hemingway⑭或After the Deadline⑮之类的工具）。

使用单元测试文档的理念可以确保公司各个部门之间文档的标准化。

在 DevOpsDays NYC2015 关于文档的讨论中，来自 Etsy⑯ 的 Mike Rembestsy⑰ 将他们的流程描述为「对数据中心的网络基础结构进行动态记录」：

Etsy 使用 Chef 来更新他们的基础结构，同时 Chef 脚本动态地更新Nagios⑱，监视实例与动态编辑、发布网络图。

通过在文档中使用 DevOps 的手段，Etsy 的工程师实现了更新文档的过程自动化，这样在他们完成工作的时候顺便就完成了这一过程。这些理念与实践在保证文档精准的同时，也反映了系统的当前状态。

我们的建议是：将文档当作源代码管理，使得信息版本化，并允许个人有能力维护或将较小的数据来源与各类文档材料自动合并。

处理可控数据可以通过有效利用安排，将降低上下文切换所带来的不利影响⑲。

切换到 DevOps 文档流程与工作流程时，需要转换思想，考虑什么工具对生成文档最为必要。团队在信息生成时越自动化，或者在促进信息管理时越有效，文档的质量与可用性也就越高。

最终，以 DevOps 为基础的文档就能够允许所有利益相关者访问一份通用、可信的信息源，来了解项目详情了。

① essays/agileDocumentationBestPractices.htm
② post.cfm/continuous-integration-in-devops
③ [/url]
④ [url]
⑤ technetwork/articles/java/index-jsp-135444.html
⑥ [/url]
⑦ [url]wiki/Doxygen
⑧ questions/106202/my-boss-wants-a-narrated-line-by-line-english-explanation-of-our-code
⑨ post.cfm/generalized-model-automated-devops-153
⑩ post.cfm/field-study-technical-debt-208
⑪ minimum-viable-product/
⑫ business/15/7/documentation-devops
⑬ thatdocslady
⑭ [/url]
⑮ [url]
⑯ [/url]
⑰ [url]mrembetsy
⑱ [/url]
⑲ [url]post.cfm/addressing-detrimental-effects-context-switching-devops-064

（王鹏高浩淼原创）