璧水(师徒h)璧水(师徒h)首页

将想法与焦点和您一起共享

及时更新网站文档发布者:本站     时间:2020-02-12 10:02:32

即使在一些有着稳健和健康的文档编写文化的组织中,应用的进化和修改速度也会远远快于文档编写速度。现实情况是软件变化速度远远快于文档编写速度,即使有自动化文档系统,有时候我们仍然需要人工编写一些文档。这种文档需要通过一定的技术转换,方能提供给在特殊阅读环境中的读者阅读,因此无法通过自动化方法维护。
 
API参考文档以及其他高度技术化的文档,则很可能通过编程语言平台的自动化文档编写机制完成(如Java的 Javadoc、Ruby的RDoc Python的 Pydoc等)。然而,有些需要人类表达(这是最宝贵的交流方式)的文档,则不像技术文档一样与应用程序和基础架构有紧密关系。为此,技术文档可能在一个月内(或更短的时间内)就会过期,而有一些文档可能几年时间都未曾更新过一一不过,这种情况实际上比没有技术文档还要槽,因为会进上程帅以为不需要从别处获取信息,而误认为这些过期文档就是正确的信息。

除此之外,当文档创建后,许多工程师就不会再更新文档了。定期检查文档才能让文档保持最新状态。
 
解决方法:通知工程师更新文档
 
在整个组织范围内,人们不太可能详细阅读文档管理系统(如Wi) 中的所有文档,但在一个部门级别上,却可能会出现一些文档修改和编辑。但是,使用随机方法的效率是远远不够的,我们必须通过某种机制,让文档管理系统能够通知文档所有人或管理员,让他们在一段时间后更新文档。开源Wiki系统 Twiki提出了一种解决方案,它的页面像报纸一样在时间长了之后会变黄。而且,在系统认为文档可能需要更新时,它会向文档所有人发送一封通知邮件。
 
但只有工具还不够,运维与开发团队还必须转变认识,他们必须将使用文档视为一种软件改进手段。例如,需要更新的页面会变成黄色但这并不意味着有人会去更新它。必须有人去响应这个通知,如果接收者不理解创建及维护文档对于代码和系统的价值,那么这个响应可能就不会出现。如果技术人员知道当文档需要更新时,系统才会通知他们,那么当他们接收到一个通知时,他们就很可能会跟进处理这个通知。这似乎有一些琐碎,但是对技术人员予以告知可以鼓励他们认真对待文档。
 
好处:将文档整合到常规活动中
 
当网站设计开发人员习惯了接收更新通知并响应这些通知之后,他们就会看到文档在改进软件方面的价值,这样将进一步激励他们及时响应通知。构成大型网站基础架构的软硬件通常由一定数量的位于数据中心内的服务器组成。目前,这些基础架构的安装及维护在一定程度上仍然通过人工方式完成。我们将介绍随着计算领域内的突破性进展,虚拟化基础架构是如何减少人工需求的,以及如何实现其中一些流程的自动化。不过,在考虑实施自动化之前,最好先了解一下当前的工作流程。