标签：
写文档的重要性
对于软件相关行业，在学校或单位大家也许都已经注意到了，除了要编写的程序、绘制设计图之外，还有一个重要的工作便是写文档。为什么要写文档呢？因为我们要把自己做的东西展示出来，不光展示给同行看，可能还要展示给其他岗位上的工作人员看，甚至展示给用户看。如果我们只是会写程序，不会在文档中恰当且优雅地描述自己的想法，那么就真正的成为“码农”了。
我注意了一下，周围的同事会写高质量文档的确实很少。李开复老师在《浪潮之巅》的序言中说到：“我认识很多顶尖的工程师，但具备强大叙事能力的优秀工程师，我认识的可以说是凤毛麟角。”确实，我所认识的同事，能够在文档中清晰地表达自己想法的也很少。
有关文档书写，我印象很深的问题有如下几个方面：
有关计算机软件的传统定义为：软件是计算机系统中与硬件相依存的另一部分，软件包括程序、数据及其相关文档的完整集合。注意，这里面就提到了“相关文档”，如果文档没有写好，那么软件也不能算是优秀的软件。事实上，软件功能健全，而由于文档原因出现故障的情况还时有发生。
一般说来，在软件开发过程中，不同阶段涉及到的主要文档如下图所示：
可见，在软件的不同阶段，需要编写不同的文档。在计划阶段，需要编写详细设计文档、单元测试方案文档和集成测试方案文档等；在开发阶段，也是这几个文档，不过是修订版，因为我们在实际开发过程中，会发现之前设计不合理的地方或者是考虑不周的地方，这就需要对之前的文档进行修改；在测试阶段，要编写单元测试报告、集成测试报告和系统测试报告等；在软件的发布阶段，要编写安装手册、用户手册、升级指导书等，这些文档主要是面向现场支持人员和用户的，因此要尽量写得通俗易懂，千万不要有模棱两可的情况存在，否则就只有等待用户的投诉了。
要想写好文档，我们需要首先纠正一个观念：文档不重要。要把文档放在与程序同等重要的位置。
如何写出高质量文档？
那么，我们如何才能写出高质量的文档呢？我认为可以从如下几个方面着手：
总的说来，和做其它事情一样，书写文档也反映了一个人的态度问题。写出高质量的文档，不仅可以提升个人的形象（如果你看到一篇好文档，是不是也对作者有较高的评价？），还能够提升产品在客户心中的形象。如此分析，多花些心思来书写文档真的是很有必要。
要想做好一件事情，需要我们从各个方面来努力。在开发软件的过程中，写好代码很重要，清楚明了地在文档中表达自己思想同样非常的重要。“代码”和“文档”就像是一个人的左膀右臂，一定要让两者均衡发展，而不能够只顾其一。
(原文链接：http://www.csdn.net/article/2014-08-12/2821148)
在实际的软件开发工作中，除了编写代码之外，程序员还会花大量的时间来编写相关的研发文档，这些文档包括：详细设计文档、单元/集成测试文档、软件版本开发报告、软件安装说明、软件升级指导书等。
在《程序员既要写好代码，又要写好文档》(http://www.zhouzhaoxiong.com/142.html)一文中，我提到过：“代码”和“文档”就像是一个人的左膀右臂，一定要让两者均衡发展，而不能够只顾其一。既然文档这么的重要，那么对于程序员来说，我们如何才能写出一份好的文档呢？根据我个人的经验，我们不妨从以下方面入手：
第一，将重要的内容分点描述，而不是杂糅在一起。
例如，有一段描述某软件功能的话是这样的：
该软件模块在系统中占有重要的地位，它从客户提供的FTP目录下获取文件，并下载到本地的目录中。接着，它扫描本地目录，对读取到的文件的内容进行解析，并生成新的文件放到本地的另一目录中。然后，它将该目录中的文件上传到客户指定的FTP目录中。对于本地目录中的文件，该模块有一个过期清理的机制，清理时间及过期期限可配置。
我们可以看到，上面那段话将软件功能描述放到一个段落中，读起来让读者云里雾里的。我们可以把内容分点描述，如下：
该软件模块在系统中占有重要的地位，其实现的主要功能为：
(1)从客户提供的FTP目录中下载文件到本地的目录中。
(2)从本地目录中获取文件进行解析，并生成新的文件放到本地的另一目录中。
(3)将目录中生成的文件上传到客户指定的FTP目录中。
(4)清理本地目录中的过期文件(清理时间及过期期限可配置)。
这样修改之后，文章的逻辑更加的清晰，可读性更强，读者也更容易理解作者所要表达的意思。
第二，将流程性比较强的内容画成流程图，而不是仅用文字描述。
一篇图文并茂的文章才是好文章，如果大家看到一篇好几十页的文章全是文字，很容易失去阅读的兴趣。对于某些流程性比较强的内容，如果将文字变成流程图，则给读者的感觉是不一样的。
例如，下面一段文字描述了socket的整个消息流程：
第一步，创建socket。
第二步，绑定指定的IP地址和端口。如果绑定失败，则跳到第一步。
第三步，启动监听。如果没有监听到消息，则程序一直处于监听状态；如果监听到了消息，则执行下一步。
第四步，循环从监听队列中获取消息，并根据消息内容执行相关的操作。
将文字内容画成流程图，如下所示：
从流程图中，我们更容易看出程序的逻辑，让读者在一段轻松的阅读旅程中理解作者所要表达的意思。
第三，将带数字的内容以图表的形式呈现，而非用文字描述。
对于某些有参照性质的数字，我们可以用图表的形式来呈现，这样可以让读者看到相邻几组数字的变化情况，文章的表达效果更好。
例如，有下面一段描述：
今年3月份，解决的软件bug数量为8；今年4月份，解决的软件bug数量为6；今年5月份，解决的软件bug数量为10。
可以将以上内容替换成下面的图表：
从图中，我们更容易看出前后数字的变化情况，对所描述事物有一个整体的把握。
第四，尽量不要直接在文档中贴代码，而换之以伪代码、流程图等形式。
也许是为了省事，很多程序员喜欢将工程代码直接粘贴到文档中，这不仅会占用大量的文档篇幅，而且会降低文档的可读性。试想，一个从没有接触过代码的人，如何能够看懂你在文档中给出的代码？即使对于有经验的程序员来说，一眼看到你写出来的程序，也不见得能够一下就明白的。
如果你写的代码确实很好，想给别人看，那么在正文中可以只给出设计思想、流程图等，而在附录中给出完整的代码。
以上几点写文档的建议是本人在写文档过程中的一些心得体会，不见得都正确，大家可以参考。总的说来，文档的编写要遵循简单易懂的原则，要用最直接明了的方式来表达作者本人的意思。
爱因斯坦曾说过：“科学家应该使用最简单的手段达到他们的结论，并排除一切不能被认识到的事物”。也就是说，简单就是美。这个“简单”的原则同样可以应用到文档编写中，应用到所有的软件开发项目中。
标签：
原文地址：http://www.cnblogs.com/myohao/p/4937031.html
