程序员写文档的重要性

写文档的重要性

对于软件相关行业&＃xff0c;在学校或单位大家也许都已经注意到了&＃xff0c;除了要编写的程序、绘制设计图之外&＃xff0c;还有一个重要的工作便是写文档。为什么要写文档呢&＃xff1f;因为我们要把自己做的东西展示出来&＃xff0c;不光展示给同行看&＃xff0c;可能还要展示给其他岗位上的工作人员看&＃xff0c;甚至展示给用户看。如果我们只是会写程序&＃xff0c;不会在文档中恰当且优雅地描述自己的想法&＃xff0c;那么就真正的成为“码农”了。

有关文档书写&＃xff0c;我印象很深的问题有如下几个方面&＃xff1a;

1. 我们每天都会收发很多邮件&＃xff0c;我仔细看了一下&＃xff0c;很多邮件里面的内容要么语句不通顺、要么有很多错别字、要么误用或没有标点符号。很多时候&＃xff0c;从不同的角度理解&＃xff0c;一封邮件有很多不同的意思&＃xff0c;让人感觉不知道它究竟要表达一个什么意思&＃xff0c;这样极大地降低了工作的效率。
2. 除了代码之外&＃xff0c;项目也会包含了大量的文档。打开大部分文档&＃xff0c;看到的第一眼&＃xff0c;我就有这几种感觉&＃xff1a;排版不工整、格式不正确、语句不通顺、错别字连篇。一看就知道作者没有认真写文档&＃xff0c;并且语句的表达和组织能力也不强。
3. 在项目小组成员讨论的时候&＃xff0c;大家几乎都在说怎样把程序写好&＃xff0c;而没有提到在文档书写方面应如何努力去改进。大家似乎一致认为开发人员的职责就是把程序写好&＃xff0c;其它什么的都是其次的。

有关计算机软件的传统定义为&＃xff1a;软件是计算机系统中与硬件相依存的另一部分&＃xff0c;软件包括程序、数据及其相关文档的完整集合。注意&＃xff0c;这里面就提到了“相关文档”&＃xff0c;如果文档没有写好&＃xff0c;那么软件也不能算是优秀的软件。事实上&＃xff0c;软件功能健全&＃xff0c;而由于文档原因出现故障的情况还时有发生。

一般说来&＃xff0c;在软件开发过程中&＃xff0c;不同阶段涉及到的主要文档如下图所示&＃xff1a;

可见&＃xff0c;在软件的不同阶段&＃xff0c;需要编写不同的文档。在计划阶段&＃xff0c;需要编写详细设计文档、单元测试方案文档和集成测试方案文档等&＃xff1b;在开发阶段&＃xff0c;也是这几个文档&＃xff0c;不过是修订版&＃xff0c;因为我们在实际开发过程中&＃xff0c;会发现之前设计不合理的地方或者是考虑不周的地方&＃xff0c;这就需要对之前的文档进行修改&＃xff1b;在测试阶段&＃xff0c;要编写单元测试报告、集成测试报告和系统测试报告等&＃xff1b;在软件的发布阶段&＃xff0c;要编写安装手册、用户手册、升级指导书等&＃xff0c;这些文档主要是面向现场支持人员和用户的&＃xff0c;因此要尽量写得通俗易懂&＃xff0c;千万不要有模棱两可的情况存在&＃xff0c;否则就只有等待用户的投诉了。

要想写好文档&＃xff0c;我们需要首先纠正一个观念&＃xff1a;文档不重要。要把文档放在与程序同等重要的位置。

如何写出高质量文档&＃xff1f;

那么&＃xff0c;我们如何才能写出高质量的文档呢&＃xff1f;我认为可以从如下几个方面着手&＃xff1a;

1. 改变文档为辅的观念&＃xff0c;在平常的工作中&＃xff0c;对于自己编写的每一份文档&＃xff0c;均认真对待。
2. 对于邮件的编写&＃xff0c;要把自己想说的话准确地表达出来&＃xff0c;在发送邮件之前&＃xff0c;再看一下内容是否完整、是否还有错别字、语句是否通顺等。
3. 在编写文档的过程中&＃xff0c;要严格参照项目组规定的模板来完成。在写完文档之后&＃xff0c;对文档进行语法检查&＃xff0c;以纠正错别字和有语法错误的地方。一般说来&＃xff0c;有语法错误的语句下面会有一条绿色的波浪线。在提交文档之前&＃xff0c;再通读一下整个文档&＃xff0c;看是否还有疏漏和不足。
4. 在工作之余&＃xff0c;可以读一些能够提高语言表达能力和写作能力的书籍或文章&＃xff0c;看一下别人是怎样清晰地阐述自己思想的。例如&＃xff0c;经常阅读CSDN上面优秀博主的博文就是一个提高自己写作能力的好办法。

总的说来&＃xff0c;和做其它事情一样&＃xff0c;书写文档也反映了一个人的态度问题。写出高质量的文档&＃xff0c;不仅可以提升个人的形象&＃xff08;如果你看到一篇好文档&＃xff0c;是不是也对作者有较高的评价&＃xff1f;&＃xff09;&＃xff0c;还能够提升产品在客户心中的形象。如此分析&＃xff0c;多花些心思来书写文档真的是很有必要。

要想做好一件事情&＃xff0c;需要我们从各个方面来努力。在开发软件的过程中&＃xff0c;写好代码很重要&＃xff0c;清楚明了地在文档中表达自己思想同样非常的重要。“代码”和“文档”就像是一个人的左膀右臂&＃xff0c;一定要让两者均衡发展&＃xff0c;而不能够只顾其一。