DevOps：怎么实现源代码注释和系统文档的自动化更新？

DevOps：怎么实现源代码注释和系统文档的自动化更新？

问题流程

创建、维护用户文档与系统文档时，操作人员通常会使用笨重的二进制文档（比如 * .docx）。一般来说，在文档协作体系中，还包括一长串来来回回的电邮，或者网络共享的文件，人们使用这些形式相互传送文档的更新版本。此外，专用格式（ * .docx 与生成的 PDF）往往会因为跨系统操作而产生不一致，从而在跨团队合作时，常常因为工作环境不同而产生数据损毁。

将二进制文件存储在版本控制系统中是一种解决办法，但管理多个版本的二进制文件仍旧极具挑战。采用自动化文档，并将它们集成在软件开发生命周期（SDLC）中同样存在许多问题：随着项目的进程，这些文档经常会更新地越来越少，或者被完全废弃。大量文档就是个反面教材（使用不当手段解决问题）；每支团队都应当在丰富与简单之间找到平衡。

文档代码「不分家」

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

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

在所有信息存好之后，我们就可以通过工具来撰写大家能够阅读并理解的文档，来为读者提供信息。这些撰写的材料一旦生成，就不再更改，以作参考信息；生成文档的流程是获取最新数据的方法。将文档材料作为网页上传是保存这类文档的一个完美手段，因为网页显示的总是最新版本的文档。

源代码

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

系统、设计和用户文档

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