软件心学格物致知篇(7)软件开发文档写什么

前言

当今约束大家生产力的有哪些因素？是编程语言？开发框架？开发IDE？还是自身迫切需要更高水平的技能？

好像上面的每一项技术都在不断发展，也在不断的为我们生产了提高做贡献，其中还孕育出了几家很不错的公司。

但是关于写文档这块好像这么多年从未有所大的变化，上一次关于文档话题的激烈争辩貌似还是雪鸟会议上提出的敏捷宣言。

文档问题与期望

在大多数的项目中，文档的编写本身都是作为一项独立的活动进行的。或是在其他活动之前，或是在其他活动之后。总之它无法根据其他活动的变更而进行自动变更。

文档依赖手工编写，不同的人由于文字表达能力、习惯等不同吗，写出的文档形式和内容都有差异。同样会给不同的阅读者带来不同的体验。

很多人不喜欢写文档，其中一个原因是因为文档本身就是知识的冗余。文档中表达的知识特，特别是业务逻辑会使用代码在软件中再表达一次。有的甚至在不同文档中还要多次表达相同的知识。

文档通常被当作其他活动的附属物，主要是为了应付某些工作，早已失去了其真实价值。长此以往造成恶性循环。

此外错误的文档有时候不仅仅无法带来帮助，可能还会带来误导性帮助。一些错误的知识会引发比没有文档还严重的问题。

所以你要维护高质量的文档，你或组织必须投入非常多的资源。组织和我们每个人一样，很多时候不愿意付出这些资源。

说了这么多编写好文档的困难和问题，那么大家心目中理想的文档也呼之欲出了，我们期望中的好文档应该具备：实用、最新、成本低、有趣的特征。

这篇文章并不谈如何写出具备这几个特征的好文档，而是先谈谈文档里值得被写入的是什么。只有先理解什么东西是应该存储进文档。文档的价值是什么，我们下一步再考虑如果写好他它。

文档编写的是知识

软件开发过程需要文档，确切的说，工程师需要的是记录在文档里的知识而并非信息。如果文档里只有信息，那么信息还需要被进一步加工成知识，然后工程师们根据知识来进行决策。

那么问题来了，如果文档里只有信息，不同的人对信息进行加工的能力是不同的。这个过程会受到加工人的知识体系、职业背景、思维偏好等影响。

所以软件需求规格说明书或产品规格说明书中记录的是关于产品的知识，概要设计文档或详细设计文档中记录的是关于软件架构、接口、数据库等如何设计系统的知识。

在编写文档的知识，我们应该尽量让大脑中的知识输出到文档里，而不是在文档里堆砌信息。否则一旦旧的人员离开了，他们就会带着知识一并离开。而新成员只能捧着一堆包含信息的文档，组织将永远失去那些对做决策有重大作用的知识。

软件开发的源代码也是一类文档，如果源代码是给机器看的，那么源代码只要作到信息这个程度就够了，因为机器只会按照预先设定好的逻辑(各种功能不同寄存器各司其职来完成)去执行。

但是源代码的受众其实是开发者，是人，所以源代码应该以知识的方式呈现，需要遵循一定的规范、设计、注释等。源代码的知识是为了让其他人了解已经完成的工作，以便他们更好、更快地完成之后的工作。

当源代码文档缺失知识时，就会导致两种后果：浪费时间和次优决策。

我们需要花费时间去寻找丢失的知识，还不一定找的回，本来这个时间可以更好的投入到其他方面的改进上。

我们每次做的决策因为缺乏足够正确的知识，就会变成次优决策，本来我们可以有更好的决策，让系统更好，成本更低。

随着系统开发时间的推移，浪费时间和次优决策的影响会不断叠加。系统上每一次决策都劣于前一次，最终我们的系统积重难返，开发者们别无选择，只能选择不再维护并重新开发。

从某种意义上讲，源代码其实是开发者头脑中的心智模型。

存储后还要传递

既然文档中记录的是知识，是不是就够了？

当然不是！如果文档只记录知识，那么只要书写人自己看懂就行了。

文档更重要价值体现在把存储的知识传递出去！

那么哪些知识值得被记录到文档里进行传递呢？大概有以下三种：

• 很多人感兴趣的知识
• 长期令人感兴趣的知识
• 有价值或重要的知识

另外为了将文档中存储的知识更好的传递出去，我们为此还发明了各种把文档写得更方便阅读以便于更有效传播的方法：MECE法则、总分总结构、图文并茂、逻辑清晰无歧义等等。

小结

请记住文档里应该记录存储的是知识而不是信息。

人类文明的传承依赖的就是知识的传递，文档是其中一个很重要载体。