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

第一，将重要的内容分点描述，而不是杂糅在一起。

例如，有一段描述某软件功能的话是这样的：

该软件模块在系统中占有重要的地位，它从客户提供的FTP目录下获取文件，并下载到本地的目录中。接着，它扫描本地目录，对读取到的文件的内容进行解析，并生成新的文件放到本地的另一目录中。然后，它将该目录中的文件上传到客户指定的FTP目录中。对于本地目录中的文件，该模块有一个过期清理的机制，清理时间及过期期限可配置。

我们可以看到，上面那段话将软件功能描述放到一个段落中，读起来让读者云里雾里的。我们可以把内容分点描述，如下：

该软件模块在系统中占有重要的地位，其实现的主要功能为：

(1)从客户提供的FTP目录中下载文件到本地的目录中。

(2)从本地目录中获取文件进行解析，并生成新的文件放到本地的另一目录中。

(3)将目录中生成的文件上传到客户指定的FTP目录中。

(4)清理本地目录中的过期文件(清理时间及过期期限可配置)。

这样修改之后，文章的逻辑更加的清晰，可读性更强，读者也更容易理解作者所要表达的意思。

第二，将流程性比较强的内容画成流程图，而不是仅用文字描述。

一篇图文并茂的文章才是好文章，如果大家看到一篇好几十页的文章全是文字，很容易失去阅读的兴趣。对于某些流程性比较强的内容，如果将文字变成流程图，则给读者的感觉是不一样的。

例如，下面一段文字描述了socket的整个消息流程：

第一步，创建socket。

第二步，绑定指定的IP地址和端口。如果绑定失败，则跳到第一步。

第三步，启动监听。如果没有监听到消息，则程序一直处于监听状态；如果监听到了消息，则执行下一步。

第四步，循环从监听队列中获取消息，并根据消息内容执行相关的操作。

从流程图中，我们更容易看出程序的逻辑，让读者在一段轻松的阅读旅程中理解作者所要表达的意思。

第三，将带数字的内容以图表的形式呈现，而非用文字描述。

对于某些有参照性质的数字，我们可以用图表的形式来呈现，这样可以让读者看到相邻几组数字的变化情况，文章的表达效果更好。

第四，尽量不要直接在文档中贴代码，而换之以伪代码、流程图等形式。

也许是为了省事，很多程序员喜欢将工程代码直接粘贴到文档中，这不仅会占用大量的文档篇幅，而且会降低文档的可读性。试想，一个从没有接触过代码的人，如何能够看懂你在文档中给出的代码？即使对于有经验的程序员来说，一眼看到你写出来的程序，也不见得能够一下就明白的。

如果你写的代码确实很好，想给别人看，那么在正文中可以只给出设计思想、流程图等，而在附录中给出完整的代码。

以上几点写文档的建议是本人在写文档过程中的一些心得体会，不见得都正确，大家可以参考。总的说来，文档的编写要遵循简单易懂的原则，要用最直接明了的方式来表达作者本人的意思。

爱因斯坦曾说过：“科学家应该使用最简单的手段达到他们的结论，并排除一切不能被认识到的事物”。也就是说，简单就是美。这个“简单”的原则同样可以应用到文档编写中，应用到所有的软件开发项目中。