作为一个长期在CSDN社区工作的人，我很佩服很多高流量的博主，尤其是在我参加了“2014CSDN博文大赛”之后，《2015CSDN-Markdown博文大赛》，看到活动中的一些参赛作品条理清晰，文笔流畅，语言优美，而且大部分都是程序员写的，不禁想到一个问题：程序员要不要注意写文档?写文档的重要性对于软件相关的行业，在学校或者单位的大家可能都注意到了，除了写程序、画设计图之外，还有一个重要的工作就是写文档。为什么要写文档？因为我们要展示我们做的东西，不仅要给同行看，还要给其他岗位的工作人员看，甚至给用户看。纪录片真正成为“码农”。我发现身边确实很少有同事能写出高质量的文档。李开复老师在《浪潮之巅》的序言中说：“我认识很多优秀的工程师，但我认识的优秀工程师却很少有很强的叙事能力。”确实，我认识的同事能把自己的想法表达清楚的文档很少。关于文件的写作，让我印象深刻的问题如下：1.我们每天收发大量的邮件。没有标点符号。很多时候，一封邮件从不同的角度看，有很多不同的含义，让人感觉不知道它到底想表达什么意思，大大降低了工作效率。2.除了代码，项目还会包含大量的文档。当我打开大部分文档时，第一眼有以下感受：排版不工整，格式不正确，句子不流畅，错别字多。一看就知道是作者写文档不仔细，语句的表达和组织能力不强。3、项目组成员在讨论的时候，几乎所有人都在讨论如何把程序写好，而没有提到如何改进文档的编写。每个人似乎都同意开发人员的责任是把程序写好，其他都是次要的。计算机软件的传统定义是：软件是计算机系统中依赖于硬件的另一部分，软件包括程序、数据和相关文件的完整集合。注意这里提到的是“相关文件”。如果文档写得不好，那么这个软件就不能算是优秀的软件。其实软件是完美功能的，还是会出现因为文档原因出现故障的情况。一般来说，在软件开发过程中，不同阶段涉及的主要文档如下图所示：可见，在软件的不同阶段需要编写不同的文档。在策划阶段，需要编写详细的设计文档、单元测试计划文档、集成测试计划文档等；在开发阶段，也会对这些文档进行修改，因为我们在实际开发过程中会发现之前的设计不合理，没有考虑周全的地方，需要对之前的文档进行修改；在测试阶段，需要编写单元测试报告、集成测试报告和系统测试报告等；在软件发布阶段，需要编写安装手册、用户手册、升级指南等，这些文档主要是给现场支持人员和用户使用的，所以尽量写得通俗易懂，不能有空缺含糊不清，否则我们将不得不等待用户投诉。要想写出好的文档，首先要纠正一个观念：文档不重要。文档应该和程序放在同样重要的位置。#p#程序员如何写出高质量的文档？既然文档这么重要，那么我们如何才能为程序员写出好的文档呢？根据我个人的经验，我们不妨从以下几个方面入手：***，把重要的内容分点描述，不要混在一起。例如，有一段描述某款软件的功能：该软件模块在系统中占有重要地位，它从客户提供的FTP目录中获取文件，并下载到本地目录中。然后，它会扫描本地目录，解析读取到的文件内容，并生成一个新文件放在另一个本地目录中。然后它将该目录中的文件上传到客户指定的FTP目录。对于本地目录下的文件，本模块有过期清理机制，可以配置清理时间和过期时间。我们可以看到，上面一段把软件功能描述放在了一段话里，让读者在阅读的时候一头雾水。内容分几部分描述如下：该软件模块在系统中占有重要地位，其主要功能有：(1)从客户提供的FTP目录下下载文件到本地目录。(2)从本地目录获取文件进行解析，生成新文件放到本地另一个目录下。(3)将目录中生成的文件上传到客户指定的FTP目录中。(4)清理本地目录下的过期文件（可配置清理时间和过期时间）。经过这样的修改，文章的逻辑更加清晰，可读性更强，读者也更容易理解作者想表达的意思。第二，将程序性较强的内容画成流程图，而不是仅仅用文字描述。图文并茂的文章才是好文章。如果你看到一篇文章，几十页满是文字，很容易失去阅读兴趣。对于一些流量很强的内容，如果把文字变成流程图，会给读者不一样的感受。例如，下面一段描述了套接字的整个消息流：第一步是创建一个套接字。第二步绑定指定的IP地址和端口。如果绑定失败，则跳至第一步。第三步，开始监控。如果没有检测到消息，则程序一直处于监听状态；如果检测到消息，则执行下一步。第四步，循环从监听队列中获取消息，根据消息内容进行相关操作。将文字内容画成流程图，如下图：从流程图中，我们更容易看出程序的逻辑，让读者在轻松的阅读旅程中理解作者想要表达的意思。第三，以图表的形式用数字呈现内容，而不是用文字描述。对于一些参考数字，我们可以用图表的形式呈现，让读者看到相邻几组数字的变化，文章的表达效果更好。例如，有如下描述：今年3月，解决软件BUG数为8；今年4月，解决软件BUG数量为6个；今年5月份解决的软件BUG数量为10个，以上内容可以用下面的图表代替：从图表中我们更容易看出前后数字的变化，对整体有一个整体的认识对所描述事物的把握。四、文档中尽量不要直接粘贴代码，而是用伪代码、流程图等替代文件空间大，同时也降低了文件的可读性。试想一下，一个没有接触过代码的人，怎么可能看懂你在文档中给出的代码呢？即使是经验丰富的程序员，一眼看到你写的程序也未必能一下子看懂。如果你写的代码真的很好，想给别人看，只能在文中给出设计思路、流程图等，在附录中给出完整的代码。以上几点写文档的建议是我在写文档的过程中的一些经验，并不是全部都是正确的，大家可以参考一下。一般而言，文件的书写应遵循通俗易懂的原则，以最直接明了的方式表达作者自己的意思。爱因斯坦曾说过：“科学家应该用最简单的手段得出结论，排除一切不能被认可的东西”。也就是说，简单就是美。这种“简单”的原则也适用于文档，适用于所有的软件开发项目。其他一些建议1.改变文件是补充的观念。在平时的工作中，认真对待自己写的每一份文件。2.邮件的写作，一定要准确表达你想说的内容。发送邮件前，检查内容是否完整，是否有错别字，句子是否流畅等。3.在撰写文档的过程中，必须严格按照项目组指定的模板完成。写完文档后，对文档进行语法检查，纠正拼写错误和语法错误。一般来说，有语法错误的语句下面会有一条绿色波浪线。在提交文件之前，通读整个文件，看看是否有任何遗漏和不足。4、闲暇之余，可以阅读一些可以提高语言表达能力和写作能力的书籍或文章，看看别人是如何清晰地表达自己的想法的。比如经常阅读CSDN上优秀博主的博文，是提高写作水平的好方法。总之，写文档和做其他事情一样，是一个态度问题。写出高质量的文档不仅可以提升个人形象（看到好的文档，是不是对作者的评价也很高？），也可以提升产品在客户心中的形象。经过这样的分析，确实有必要多花点时间写文档了。做好一件事，需要从各方面下功夫。在开发软件的过程中，写出好的代码很重要，在文档中清楚地表达自己的想法也很重要。“代码”和“文档”就像一个人的得力助手。一定要让两者平衡发展，不能只关注一个。来源：zhouzx
