随想录（软件文档的重要性）

Posted 2022-01-19 费晓行

【 声明：版权所有，欢迎转载，请勿用于商业用途。 联系信箱：feixiaoxing @163.com】

    对于大多数程序员来说，他们喜欢写代码、写算法、写多线程、写很多牛逼的功能，但是一谈到文档，就头疼，至少从心底来说，就很抵触。其实，这根本没有必要，相比较编写文档的时间，编写文档带来的益处是非常多的。

1、文档会让自己有全局的软件视角（非常重要）

    相比较具体的技术，软件开发中一般要编写很多的文档。需求文档、架构文档、详细设计文档、测试文档、交付文档、使用手册等等。每一个文档都有自己的意义。只有对全局有一个整体的认识，才知道自己开发工作的价值。

需求文档：将用户的需求变成程序员可以理解的流程

架构文档：将流程结合技术构建最小系统，类似于硬件那种最小系统

详细设计文档：将最小系统拓展为产品，增加功能、界面、交互、调试、性能、数据库、插件等更多内容

测试文档：判断软件是否稳定高效运行、满足需求

交付文档：软件怎么部署

使用手册：交给客户的使用手册

2、笔记的作用

    时间长了，可能就不知道当初为什么要开发这个功能。有个文档，至少可以帮助我们回忆一下，当初为什么要这么设计。

3、软件质量的保证（非常重要）

    很多同学认为软件质量是测试人员的事情，这是非常错的。如果最初的需求分析和架构设计就是错的，质量无从谈起。方向在一开始就搞错了，后面再怎么弥补都无济于事。

4、软件协作的基础

    即使都是做软件开发的同学，相互之间的工作其实也是有差别的。有的负责需求分析，有的负责架构设计，有的负责重点技术攻关，有的负责售前售后，这都很正常。如果正常大家的交流都靠微信、邮箱去交流，没有统一的文档，这效率就非常低了，而且相互之间容易扯皮。

5、文档和软件一样需要维护、更新（很重要）

    软件发生变更修改的时候，一定要对文档进行统一的修改。只有保证文档和软件保持一致，才能最大程度保证文档的价值。如果所有人都认为目前的文档已经过时了，那么这个文档基本上也是形同虚设，大家都不会去阅读和学习的。

6、文档是重要的技术积累

    不管是对公司，还是对个人，文档都是重要的技术积累。这种积累会不断增加自己的竞争力，最大程度减少中年危机的影响。因为，不管是什么产品、什么问题，你会从正面去进行分析、解决，当初为什么有这个需求、怎么解决的、会产生什么影响，而不是遇到问题去猜、去蒙，两者解决问题的思路根本就不一样的。很多人会说老外做的东西好，因为虽然老外做的东西慢，但他们大部分是正向研究，并且有很强的文档和理论支撑，再复杂的问题都是可以解决的，只是时间的问题而已。

7、重视图、表的作用（非常重要）

    俗话说，文不如表、表不如图，适当地添加图和表的内容，可以极大地丰富资料的可读性，也会增加文档地深度和趣味性。大家多看看芯片手册，应该就有这方面的体会。