在实际的软件开发工作中，除了写代码，程序员还要花大量时间编写相关的研发文档，这些文档包括：详细设计文档、单元/集成/系统测试文档、软件版本开发报告、软件安装说明、软件升级指南、软件使用手册等。我认为：“代码”和“文档”就像一个人的得力助手，一定要让两者共同发展平衡的方式，我们不能只专注于一个。既然文档这么重要，那么我们如何才能为程序员写出好的文档呢？根据我个人的经验，我们不妨从以下几个方面入手：***，把重要的内容分点描述，而不是混在一起。例如，有一段描述某款软件的功能：该软件模块在系统中占有重要地位，它从客户提供的FTP目录中获取文件，并下载到本地目录中。然后，它会扫描本地目录，解析读取到的文件内容，并生成一个新文件放在另一个本地目录中。然后它将该目录中的文件上传到客户指定的FTP目录。对于本地目录下的文件，模块有过期清理机制，清理时间和过期时间是可配置的。我们可以看到，上面一段把软件功能描述放在了一段话里，让读者在阅读的时候一头雾水。内容分几部分描述如下：本软件模块在系统中占有重要地位，其主要功能有：从客户提供的FTP目录下下载文件到本地目录。从本地目录中获取文件进行解析，并生成一个新文件放在本地另一个目录中。将目录中生成的文件上传到客户指定的FTP目录中。清理本地目录中的过期文件（清理时间和过期时间可配置）。经过这样的修改，文章的逻辑更加清晰，可读性更强，读者也更容易理解作者想表达的意思。第二，将程序性较强的内容画成流程图，而不是仅仅用文字描述。图文并茂的文章才是好文章。如果你看到一篇文章，几十页满是文字，很容易失去阅读兴趣。对于一些流量很强的内容，如果把文字变成流程图，会给读者不一样的感受。例如，下面一段描述了套接字的整个消息流：第一步是创建一个套接字。第二步绑定指定的IP地址和端口。如果绑定失败，则跳至第一步。第三步，开始监控。如果没有检测到消息，则程序一直处于监听状态；如果检测到消息，则执行下一步。第四步，循环从监听队列中获取消息，根据消息内容进行相关操作。将文字内容画成流程图，如下图：从流程图中，我们更容易看出程序的逻辑，让读者在轻松的阅读旅程中理解作者想要表达的意思。第三，以图表的形式用数字呈现内容，而不是用文字描述。对于一些参考数字，我们可以用图表的形式呈现，让读者看到相邻几组数字的变化，文章的表达效果更好。例如，有如下描述：今年3月，解决软件BUG数为8；今年4月，解决软件BUG数量为6个；今年5月份解决的软件BUG数量为10个，以上内容可以用下面的图表代替：从图表中，我们更容易看出前后数字的变化，对整体有一个整体的认识对所描述事物的把握。四、文档中尽量不要直接粘贴代码，而是用伪代码、流程图等替代文件空间大，同时也降低了文件的可读性。试想一下，一个没有接触过代码的人，怎么可能看懂你在文档中给出的代码呢？即使是有经验的程序员，也未必能一眼就看懂你写的程序。如果你写的代码真的很好，想给别人看，只能在文中给出设计思路、流程图等，在附录中给出完整的代码。以上几点写文档的建议是我在写文档的过程中的一些经验，并不是全部都是正确的，大家可以参考一下。一般而言，文件的书写应遵循通俗易懂的原则，以最直接明了的方式表达作者自己的意思。爱因斯坦曾说过：“科学家应该用最简单的手段得出结论，排除一切不能被认可的东西”。也就是说，简单就是美。这种“简单”的原则也适用于文档，适用于所有的软件开发项目。【本文为专栏作家周兆雄原创文章，作者微信公众号：周氏逻辑（logiczhou）】点此阅读更多本作者好文
