程序员如何写出一份好的文档？

在实际的软件开发工作中，除了编写代码之外，程序员还会花大量的时间来编写相关的研发文档，这些文档包括：详细设计文档、单元/集成测试文档、软件版本开发报告、软件安装说明、软件升级指导书等。
在《程序员既要写好代码，又要写好文档》(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。

可以将以上内容替换成下面的图表：

从图中，我们更容易看出前后数字的变化情况，对所描述事物有一个整体的把握。

第四，尽量不要直接在文档中贴代码，而换之以伪代码、流程图等形式。
也许是为了省事，很多程序员喜欢将工程代码直接粘贴到文档中，这不仅会占用大量的文档篇幅，而且会降低文档的可读性。试想，一个从没有接触过代码的人，如何能够看懂你在文档中给出的代码？即使对于有经验的程序员来说，一眼看到你写出来的程序，也不见得能够一下就明白的。
如果你写的代码确实很好，想给别人看，那么在正文中可以只给出设计思想、流程图等，而在附录中给出完整的代码。

以上几点写文档的建议是本人在写文档过程中的一些心得体会，不见得都正确，大家可以参考。总的说来，文档的编写要遵循简单易懂的原则，要用最直接明了的方式来表达作者本人的意思。
爱因斯坦曾说过：“科学家应该使用最简单的手段达到他们的结论，并排除一切不能被认识到的事物”。也就是说，简单就是美。这个“简单”的原则同样可以应用到文档编写中，应用到所有的软件开发项目中。

本人微信公众号：zhouzxi，请扫描以下二维码：