让你提前认识软件开发(40)：既要写好代码，又要写好文档

第3部分 软件研发工作总结

既要写好代码，又要写好文档

 

        对于软件相关行业，在学校或单位上，大家或许都已经注意到了，除了要编写的程序、绘制设计图之外，另一个重要的工作便是写文档。为什么要写文档呢？由于我们要把自己做的东西展示出来，不光展示给同行看，可能还要展示给其他岗位上的工作人员看，甚至展示给用户看。假设我们仅仅是会敲代码，不会在文档中描写叙述自己的想法，那么就真正的成为“码农”了。

        工作也有一段时间了，我发现周围的同事，会写高质量文档的确实非常少。李开复老师在《浪潮之巅》的序言中说到：“我认识非常多顶尖的project师，但具备强大叙事能力的优秀project师，我认识的能够说是凤毛麟角。”确实，我所认识的同事，能够清晰表达自己思想的人也非常少。

        有关文档书写，我印象非常深的有例如以下几个方面：

        (1) 我们每天都会收发非常多邮件，我细致看了一下，非常多邮件里面的内容要么语句不通顺、要么有非常多错别字、要么误用或没有标点符号。非常多时候，从不同的角度理解，一封邮件有非常多不同的意思，让人感觉不知道它到底要表达一个什么意思，这样极大地减少了工作的效率。

        (2) 除了代码之外，项目也会包含了大量的文档。打开大部分文档，看到的第一眼，我就有这几种感觉：排版不工整、格式不对、语句不通顺、错别字连篇。一看就知道作者没有认真写文档，而且语句的表达和组织能力也不强。

        (3) 在项目小组成员讨论的时候，大家差点儿都在说怎样把程序写好，而没有提到在文档书写方面应怎样努力去改进。大家一直觉得开发者的职责就是把程序写好，其他什么的都是其次的。

        有关计算机软件的传统定义为：软件是计算机系统中与硬件相依存的另一部分，软件包含程序、数据及其相关文档的完整集合。注意，这里面就提到了“相关文档”，假设文档没有写好，那么软件也不能算是优秀的软件。其实，软件功能健全，而由于文档原因出现问题的情况还时有发生。

        一般说来，在软件开发过程中，不同阶段涉及到的主要文档例如以下图所看到的：

图1 软件开发不同阶段涉及到的主要文档

        可见，在软件的不同阶段，须要编写不同的文档。在设计阶段，须要编写具体设计文档、单元測试方案文档、集成測试方案文档等；在开发阶段，也是这几个文档，只是是修订版，由于我们在实际开发过程中，会发现之前设计不合理的地方或者是考虑不周的地方，这就须要对之前的文档进行改动；在測试阶段，要编写单元測试报告、集成測试报告等；在软件的公布阶段，要编写安装手冊、用户手冊、升级指导书等，这些文档主要是面向现场支持人员和用户的，因此要尽量写得通俗易懂，千万不要有模棱两可的情况存在，否则就仅仅有等待用户的投诉了。

 

       在软件产品相关文档中，具体设计文档是非常重要的。通过对设计思路的具体描写叙述，不但能够为本模块的编码工作提供必要的基础，还能够为測试人员提供一定的參考。

        一般说来，一份完整的具体设计文档的主体内容要包含如图2所看到的的9个部分。

图2 一份完整的具体设计文档的主体内容

 

        集成測试方案(规程)文档用于指导软件的集成測试工作，也是一类非常重要的文档。

        一般说来，一份完整的集成測试方案(规程)文档的主体内容要包含如图3所看到的的6个部分。

图3 一份完整的集成測试方案(规程)文档的主体内容

 

        要想写好文档，我们须要首先纠正一个观念：文档不重要。要把文档放在与程序同等重要的位置。

        那么，我们怎样才干写出高质量的文档呢？我觉得能够从例如以下几个方面着手：

        (1) 改变文档为辅的观念，在寻常的工作中，对于自己编写的每一份文档，均认真对待。

        (2) 对于邮件的编写，要把自己想说的话准确地表达出来，在发送邮件之前，再看一下内容是否完整、是否还有错别字、语句是否通顺等。

        (3)在编写文档的过程中，要严格參照项目组规定的模板来完毕。在写完文档之后，对文档进行语法检查，以纠正错别字和有语法错误的地方。一般说来，有语法错误的语句以下会有一条绿色的波浪线。在提交文档之前，再通读一下整个文档，看是否还有疏漏和不足。

        (4) 在工作之余，能够读一些能够提高语言表达能力和写作能力的书籍，看一下别人是怎么表达自己思想的。在此，推荐阅读吴军的《浪潮之巅》(http://book.douban.com/subject/24738302/)、《数学之美》(http://book.douban.com/subject/10750155/)和《文明之光》(http://book.douban.com/subject/25902942/)，以及刘未鹏的《暗时间》(http://book.douban.com/subject/6709809/)，这几本书写得都比較好。

 

        总的说来，和做其他事情一样，书写文档也反映了一个人的态度问题。写出高质量的文档，不仅能够提升个人的形象(假设你看到一篇好文档，是不是也对作者有较高的评价？)，还能够提升产品在客户心中的形象。如此分析，多花些心思来书写文档真的是非常有必要。

        要想做好一件事情，须要我们从各个方面来努力。在开发软件的过程中，写好代码非常重要，清晰地表达自己思想相同非常的重要。“代码”和“文档”就像是一个人的左膀右臂，一定要让两者均衡发展，而不能够仅仅顾其一。

 

 

             (PS：这个问题在V众投上的回答：http://www.vzhongtou.com/question/421，欢迎大家关注V众投。)

 

             (本人微博：http://weibo.com/zhouzxi?topnav=1&wvr=5，微信号：245924426，欢迎关注！)