学习
实践
活动
专区
工具
TVP
写文章

今日荐书:《活文档:与代码共同演进》

软件项目开发管理中,文档是一个绕不过的话题,并且颇有争议。

传统的项目开发管理,要求项目中文档必须按照各种标准准备好,文档先行。在软件开发过程管理中,要保证文档与软件产品的一致性,随时变更记录。这是一种非常理想的项目管理状态,但在项目实际管理中很难做到,最后的结果是软件产品与文档的不一致,导致后期运维参考文档非常困难,造成很多问题。文档最终变得鸡肋一样。

敏捷开发针对开发管理中文档弊病,强调代码重要性,代码即文档,弱化文档作用,但很多情况下,敏捷管理的执行者,常常会走向另一个极端,完全放弃文档的管理,强调代码规范和可用性,这样的结果是软件产品当时是符合用户需求的,不过一旦交付运营,或者软件需要变更,新的团队或者团队成员参与进来,就会出现信息传递上的问题,就像书中提到的,知识被局限在很狭窄的范围内,无法成为团队的知识资产被共享。

《活文档》这本书在IT技术类目中是一本比较冷门的书,很少会有一本书专门来论述如何让软件文档和软件代码共同演进,协同一致。

我们可以把这本书看做是一本活文档参考指南,它来教你如何像写代码一样有趣地持续维护文档。

书中系统地阐述了计算机软件开发各个阶段中文档写作的步骤、内容、方法、工具、特点和要求,详尽指导软件开发人员和文档开发工程师写出规范的文档,包括软件文档的概念和内容,软件文档编写的原则和步骤,软件文档的管理和维护,可行性研究报告、软件需求报告、软件测试计划等文档的写作方法和写作技巧。

《活文档》这本书强调了文档的重要性,同时也提出了如何在尽可能少增加工作量前提下,让文档与代码保持一致,能够满足开发和后续运维管理的需要。

书中核心的部分由于绑定了 BDD / DDD / TDD / XP 等等实践,甚至是 Java 语言的注解一类的细节,其实通用性是不足的,但是很多知识管理原则可以参考运用到项目文档管理当中。

比如知识定位问题,不同类型的知识,采用不同的文档维护方式,比如静态稳定的知识,可以采用传统的文档管理模式,或者wiki的形式来管理。

读完本书,在文档管理中,要关注这几个问题:

1. 首先我们真的需要这个文档吗?我们真的现在就需要这个文档吗?

2. 其他解决方案,我们可以通过对话或集中办公来分享知识吗?

3. 知识定位问题,这些知识现在在哪里?

4. 知识稳定性稳定,这些知识会如何变化?

考虑清楚这几个问题,才能让文档管理更加有效。

有了方向,具体如何将活文档这种工作模式引入现在的实际工作中落地,采用哪种活文档形式,书中都有详细的说明,可以作为工作参考手册。

  • 发表于:
  • 原文链接https://kuaibao.qq.com/s/20211231A09RUT00?refer=cp_1026
  • 腾讯「腾讯云开发者社区」是腾讯内容开放平台帐号(企鹅号)传播渠道之一,根据《腾讯内容开放平台服务协议》转载发布内容。
  • 如有侵权,请联系 cloudcommunity@tencent.com 删除。

关注

腾讯云开发者公众号
10元无门槛代金券
洞察腾讯核心技术
剖析业界实践案例
腾讯云开发者公众号二维码

扫码关注腾讯云开发者

领取腾讯云代金券