【编者按】计算机软件传统定义为:软件是计算机系统中与硬件相依存的另一部分,软件包括程序、数据及其相关文档的完整集合。然而在时下的开发中,文档的合规性往往被忽视的干干净净。本文由 Todd Waits 撰写,讲述应用程序文档化所遭遇的3个主要挑战,下面一起展开。本文系 OneAPM 联合高效运维编译整理。

通常情况下,正式的文档(如源代码文档、系统需求与设计文档,或者各类用户文档)会被开发团队忽视得彻彻底底,而 DevOps 中关于流程与文档的理念可以帮助缓解这个问题。软件文档通常分为以下几类:代码、需求、设计、系统与用户文档。文档经常会被忽略的原因之一在于,如果不能与所依赖的开发工具(如版本控制、问题追踪工具、wiki 及源代码)相匹配,标准文档工具及流程反而会对开发团队造成妨碍,并拖慢开发速度

本博文探讨了文档化所遇到的3个主要挑战:流程、注释源代码以及系统文档;同时解释了以 DevOps 为基础的文档可以通过怎样的方式使所有利益相关者得以访问通用、可信的信息源,从而查看项目的细节。

问题流程

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

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

文档代码「不分家」

理想情况下,机构应该通过规范的来源对文档进行维护与撰写。在讨论文档时,区分客观信息与主观加工过的材料非常重要。信息指的是数据或者记录的来源,而主观材料则是通过有序地组织信息而产生的可用终端产品,这种信息是可以被读者阅读的,可能包括系统需求文档、设计文档、状态报告等等。

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

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

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

源代码

长期以来,注释代码的能力都属于编程高级实践的一部分。在过去十年间,人们为了改进文档体验,为各种语言开发了不少工具。这些工具允许开发者将相关信息归档,协助开发人员理解代码。下面提到的一些工具也允许程序员在自己的文档中将测试以可读的方式添加进去。编译代码时,文档中的测试会自动运行,如果程序员修改了代码,却没有更新文档的话,build 就会失败。持续集成环境的快速反馈可以协助程序员,确保其遵守正确的文档策略。

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

通常管理者可能无法清楚应该对工程师要求什么样的文档。笔者就不止一次收到过这样的需求——将每一行代码的功能写在注释里。管理者需要了解:这类文档对程序员来说任务繁重,很快就能摧毁任何程序员在合理的时间内交付有商业价值内容的能力。

而在 DevOps 中,一切都应该被自动化,并找出可理解与简单化之间的平衡点。保持「新对象应该进行文档描述」这个思想,自动文档化所有新对象,可能是帮助程序员在代码中添加注释的好办法。但是,如果没有文档也没什么影响的话(比如引起 build 失败),你会发现一切对象都处在未归档的情况下(或者用占位符信息错误归档),从而导致返工,需要重新整理欠下的一大堆文档。

开发人员可以使用上面列出的工具来验证文档是否过期,实践效果良好。如果想在一个生命周期的结尾对该项目进行记录的话,应当在重要环节将工具打开。从项目一开始,在编写文档时着眼于每一个最小可用的产品:记录实际情况,而不是得出解决方案的过程。

系统、设计和用户文档

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

在近期的一篇博文中,Red Hat 的高级技术文档撰写者Mikey Ariel倡导使用持续集成与单元测试文档。在该文中,Ariel 将这一过程描述为:能够测试文档是否遵守指南(比如,公司使用的是 backend 还是 back-end)以及语法(利用接口使用像是HemingwayAfter the Deadline之类的工具)。使用单元测试文档的理念可以确保公司各个部门之间文档的标准化。

在 DevOpsDays NYC2015 关于文档的讨论中,来自 EtsyMike Rembestsy 将他们的流程描述为「对数据中心的网络基础结构进行动态记录」。Etsy 使用 Chef 来更新他们的基础结构,同时 Chef 脚本动态地更新Nagios,监视实例与动态编辑、发布网络图。通过在文档中使用 DevOps 的手段,Etsy 的工程师将更新文档的过程自动化,这样在他们完成工作的时候顺便就完成了这一过程。这些理念与实践在保证文档精准的同时,也反映了系统的当前状态。

将文档当作源代码管理,使得信息版本化,并允许个人有能力维护或将较小的数据来源与各类文档材料自动合并。处理可控数据可以通过有效利用安排,将降低上下文切换所带来的不利影响。切换到 DevOps 文档流程与工作流程时,需要转换思想,考虑什么工具对生成文档最为必要。团队在信息生成时越自动化,或者在促进信息管理时越有效,文档的质量与可用性也就越高。最终,以 DevOps 为基础的文档就能够允许所有利益相关者访问一份通用、可信的信息源,来了解项目详情了。

原文链接:Three Challenges to Documentation for DevOps Teams

本文系 OneAPM 工程师编译整理。想阅读更多技术文章,请访问 OneAPM 官方博客

DevOps:怎么实现源代码注释和系统文档的自动化更新?的更多相关文章

  1. Microsoft源代码注释语言(SAL)提供设置批注

    Microsoft源代码注释语言(SAL)提供设置批注可以使用描述的功能如何使用其参数,它对其假设并确保它使其在完成. 批注可标头文件 <sal.h>定义. Visual Studio C ...

  2. Vue-框架模板的源代码注释

    请稍等..吃完饭回来写 吃饭回来了~嘿 ----------------正经分割线----------------- 先看我的目录结构:这是配置好node环境和配置好webpack后,生成的原始框架. ...

  3. c语言版去除源代码注释

    去除代码中注释需要注意下面几点 首先注释有"/*"开始到"*/"结束的多行或单行注释 其次还有"//"这种单行注释 另外还需要注意双引号和单 ...

  4. zepto的源代码注释(转)

    /* Zepto v1.0-1-ga3cab6c - polyfill zepto detect event ajax form fx - zeptojs.com/license */ ;(funct ...

  5. backbone源代码注释(部分)

    // Backbone.js 1.0.0 // (c) 2010-2013 Jeremy Ashkenas, DocumentCloud Inc. // Backbone may be freely ...

  6. Hadoop 类Grep源代码注释

    /** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agree ...

  7. [转载]逐步建设企业DevOps能力

    当软件行业进入互联网时代,市场对软件产品和服务的交付提出了更高的要求:不仅要快速实现需求,而且要快速发布上线,并且必须保证业务可靠.高效运行.为了满足这些要求,IT组织需要强有力的流程.技术和人员作为 ...

  8. Visual Studio图片注释image-comments扩展

            有一个开源的Visual Studio小工具image-comments,它用于在源代码注释中插入图片,您可以到这儿下载.目前支持Visual Studio 2010/2012 Sta ...

  9. 【转载】linux环境下tcpdump源代码分析

    linux环境下tcpdump源代码分析 原文时间 2013-10-11 13:13:02  CSDN博客 原文链接  http://blog.csdn.net/han_dawei/article/d ...

随机推荐

  1. Test,Nginx Hello World Module

    ngx_addon_name=ngx_http_mytest_module HTTP_MODULES="$HTTP_MODULES ngx_http_mytest_module" ...

  2. C# WPF使用ZXing生成二维码ImageSource

    介绍: 如果需要实在WPF窗体程序中现类似如下的二维码图片生成功能,可以通过本文的方法实现 添加步骤: 1.在http://zxingnet.codeplex.com/站点上下载ZXing .Net的 ...

  3. WPF socket通讯 UDP接收消息

    客户端: private Socket socket; private IPEndPoint ipEndPoint; private void sendMessageHandler() { //服务端 ...

  4. Java Collections Source Code Series 1 --- 简介

    废话开篇 由于项目需要,需要对Java Collections进行系统地了解,所以在此记录下,方便自己,服务他人. Java Collections 简介 Java Collections 框架主要包 ...

  5. core java 5~6(OOP & 高级语言特征)

    MODULE 5 OOP 面向对象程序设计--------------------------------------------------------Object Oriented Program ...

  6. Java中的访问权限

    Java中有四种访问权限,从大到小依次是:public –> protected –> default(friendly) –> private. 简单说明下: public 作用域 ...

  7. KafkaOffsetMonitor使用方法

    (1)下载jar包 去网上搜索KafkaOffsetMonitor即可. 我这里共享了我的百度云连接:http://yun.baidu.com/s/1nvGjbDn 如果某一天我这个取消共享了,大家去 ...

  8. MongoDB学习笔记-游标

    理解MongoDB的游标有两种维度:客户端和服务器端.下面将从这两方面来说明. 客户端 find方法返回值是一个游标.可以通过游标来对最终结果进行控制.比如限制结果数量,略过某一部分,根据任意键按任意 ...

  9. 前端开发规范之html编码规范

    原则1.规范 .保证您的代码规范,趋html5,远xhtml,保证结构表现行为相互分离.2.简洁.保证代码的最简化,避免多余的空格.空行,保持代码的语义化,尽量使用具有语义的元素,避免使用样式属性和行 ...

  10. LoadRunner - 当DiscuzNT遇上了Loadrunner(下) (转发)

    当DiscuzNT遇上了Loadrunner(下) 在之前的两篇文章中,基本上介绍了如何录制脚本和生成并发用户,同时还对测试报告中的几个图表做了简单的说明.今天这篇文章做为这个系列的最后一篇,将会介绍 ...