程序员写文档的重要性
2017-03-15 22:32
435 查看
写文档的重要性
对于软件相关行业,在学校或单位大家也许都已经注意到了,除了要编写的程序、绘制设计图之外,还有一个重要的工作便是写文档。为什么要写文档呢?因为我们要把自己做的东西展示出来,不光展示给同行看,可能还要展示给其他岗位上的工作人员看,甚至展示给用户看。如果我们只是会写程序,不会在文档中恰当且优雅地描述自己的想法,那么就真正的成为“码农”了。
有关文档书写,我印象很深的问题有如下几个方面:
我们每天都会收发很多邮件,我仔细看了一下,很多邮件里面的内容要么语句不通顺、要么有很多错别字、要么误用或没有标点符号。很多时候,从不同的角度理解,一封邮件有很多不同的意思,让人感觉不知道它究竟要表达一个什么意思,这样极大地降低了工作的效率。
除了代码之外,项目也会包含了大量的文档。打开大部分文档,看到的第一眼,我就有这几种感觉:排版不工整、格式不正确、语句不通顺、错别字连篇。一看就知道作者没有认真写文档,并且语句的表达和组织能力也不强。
在项目小组成员讨论的时候,大家几乎都在说怎样把程序写好,而没有提到在文档书写方面应如何努力去改进。大家似乎一致认为开发人员的职责就是把程序写好,其它什么的都是其次的。
有关计算机软件的传统定义为:软件是计算机系统中与硬件相依存的另一部分,软件包括程序、数据及其相关文档的完整集合。注意,这里面就提到了“相关文档”,如果文档没有写好,那么软件也不能算是优秀的软件。事实上,软件功能健全,而由于文档原因出现故障的情况还时有发生。
一般说来,在软件开发过程中,不同阶段涉及到的主要文档如下图所示:
可见,在软件的不同阶段,需要编写不同的文档。在计划阶段,需要编写详细设计文档、单元测试方案文档和集成测试方案文档等;在开发阶段,也是这几个文档,不过是修订版,因为我们在实际开发过程中,会发现之前设计不合理的地方或者是考虑不周的地方,这就需要对之前的文档进行修改;在测试阶段,要编写单元测试报告、集成测试报告和系统测试报告等;在软件的发布阶段,要编写安装手册、用户手册、升级指导书等,这些文档主要是面向现场支持人员和用户的,因此要尽量写得通俗易懂,千万不要有模棱两可的情况存在,否则就只有等待用户的投诉了。
要想写好文档,我们需要首先纠正一个观念:文档不重要。要把文档放在与程序同等重要的位置。
如何写出高质量文档?
那么,我们如何才能写出高质量的文档呢?我认为可以从如下几个方面着手:
改变文档为辅的观念,在平常的工作中,对于自己编写的每一份文档,均认真对待。
对于邮件的编写,要把自己想说的话准确地表达出来,在发送邮件之前,再看一下内容是否完整、是否还有错别字、语句是否通顺等。
在编写文档的过程中,要严格参照项目组规定的模板来完成。在写完文档之后,对文档进行语法检查,以纠正错别字和有语法错误的地方。一般说来,有语法错误的语句下面会有一条绿色的波浪线。在提交文档之前,再通读一下整个文档,看是否还有疏漏和不足。
在工作之余,可以读一些能够提高语言表达能力和写作能力的书籍或文章,看一下别人是怎样清晰地阐述自己思想的。例如,经常阅读CSDN上面优秀博主的博文就是一个提高自己写作能力的好办法。
总的说来,和做其它事情一样,书写文档也反映了一个人的态度问题。写出高质量的文档,不仅可以提升个人的形象(如果你看到一篇好文档,是不是也对作者有较高的评价?),还能够提升产品在客户心中的形象。如此分析,多花些心思来书写文档真的是很有必要。
要想做好一件事情,需要我们从各个方面来努力。在开发软件的过程中,写好代码很重要,清楚明了地在文档中表达自己思想同样非常的重要。“代码”和“文档”就像是一个人的左膀右臂,一定要让两者均衡发展,而不能够只顾其一。
对于软件相关行业,在学校或单位大家也许都已经注意到了,除了要编写的程序、绘制设计图之外,还有一个重要的工作便是写文档。为什么要写文档呢?因为我们要把自己做的东西展示出来,不光展示给同行看,可能还要展示给其他岗位上的工作人员看,甚至展示给用户看。如果我们只是会写程序,不会在文档中恰当且优雅地描述自己的想法,那么就真正的成为“码农”了。
有关文档书写,我印象很深的问题有如下几个方面:
我们每天都会收发很多邮件,我仔细看了一下,很多邮件里面的内容要么语句不通顺、要么有很多错别字、要么误用或没有标点符号。很多时候,从不同的角度理解,一封邮件有很多不同的意思,让人感觉不知道它究竟要表达一个什么意思,这样极大地降低了工作的效率。
除了代码之外,项目也会包含了大量的文档。打开大部分文档,看到的第一眼,我就有这几种感觉:排版不工整、格式不正确、语句不通顺、错别字连篇。一看就知道作者没有认真写文档,并且语句的表达和组织能力也不强。
在项目小组成员讨论的时候,大家几乎都在说怎样把程序写好,而没有提到在文档书写方面应如何努力去改进。大家似乎一致认为开发人员的职责就是把程序写好,其它什么的都是其次的。
有关计算机软件的传统定义为:软件是计算机系统中与硬件相依存的另一部分,软件包括程序、数据及其相关文档的完整集合。注意,这里面就提到了“相关文档”,如果文档没有写好,那么软件也不能算是优秀的软件。事实上,软件功能健全,而由于文档原因出现故障的情况还时有发生。
一般说来,在软件开发过程中,不同阶段涉及到的主要文档如下图所示:
可见,在软件的不同阶段,需要编写不同的文档。在计划阶段,需要编写详细设计文档、单元测试方案文档和集成测试方案文档等;在开发阶段,也是这几个文档,不过是修订版,因为我们在实际开发过程中,会发现之前设计不合理的地方或者是考虑不周的地方,这就需要对之前的文档进行修改;在测试阶段,要编写单元测试报告、集成测试报告和系统测试报告等;在软件的发布阶段,要编写安装手册、用户手册、升级指导书等,这些文档主要是面向现场支持人员和用户的,因此要尽量写得通俗易懂,千万不要有模棱两可的情况存在,否则就只有等待用户的投诉了。
要想写好文档,我们需要首先纠正一个观念:文档不重要。要把文档放在与程序同等重要的位置。
如何写出高质量文档?
那么,我们如何才能写出高质量的文档呢?我认为可以从如下几个方面着手:
改变文档为辅的观念,在平常的工作中,对于自己编写的每一份文档,均认真对待。
对于邮件的编写,要把自己想说的话准确地表达出来,在发送邮件之前,再看一下内容是否完整、是否还有错别字、语句是否通顺等。
在编写文档的过程中,要严格参照项目组规定的模板来完成。在写完文档之后,对文档进行语法检查,以纠正错别字和有语法错误的地方。一般说来,有语法错误的语句下面会有一条绿色的波浪线。在提交文档之前,再通读一下整个文档,看是否还有疏漏和不足。
在工作之余,可以读一些能够提高语言表达能力和写作能力的书籍或文章,看一下别人是怎样清晰地阐述自己思想的。例如,经常阅读CSDN上面优秀博主的博文就是一个提高自己写作能力的好办法。
总的说来,和做其它事情一样,书写文档也反映了一个人的态度问题。写出高质量的文档,不仅可以提升个人的形象(如果你看到一篇好文档,是不是也对作者有较高的评价?),还能够提升产品在客户心中的形象。如此分析,多花些心思来书写文档真的是很有必要。
要想做好一件事情,需要我们从各个方面来努力。在开发软件的过程中,写好代码很重要,清楚明了地在文档中表达自己思想同样非常的重要。“代码”和“文档”就像是一个人的左膀右臂,一定要让两者均衡发展,而不能够只顾其一。
相关文章推荐
- 韩顺平_PHP程序员玩转算法公开课(第一季)01_算法重要性_五子棋算法_汉诺塔_回溯算法_学习笔记_源代码图解_PPT文档整理
- 韩顺平_PHP程序员玩转算法公开课(第一季)03_单链表crud操作之_水浒英雄排行算法_学习笔记_源代码图解_PPT文档整理
- 不会写文档的工程师不是好程序员
- 马无夜草不肥:程序员做业余项目的重要性
- 为什么公司的文档管理系统很难维护,即使是工作多年的ASP.NET程序员也这样认为?
- 程序员编程艺术第二十六章:基于给定的文档生成倒排索引(含源码下载)
- 使用 adr 轻松创建 “程序员友好” 的轻量级文档
- 论英语对提高程序员素质的必要性和重要性
- 编程基础的重要性(程序员之路)
- 文档注释的重要性,规范性。
- 从程序员到项目经理(29):怎样写文档
- 程序员需要知道的各类官方文档地址
- [转]基础的重要性(程序员之路)
- java程序员学习scala前必看的技术文档(2)
- 程序员为什么都不愿写文档
- 关于开源文档:程序员可能忽略的十件事
- C#项目程序员文档自动生成-----Sandcastle
- 项目管理——文档的重要性
- 《LLVM 程序员手册 —— LLVM 4.0 文档》 已经翻译完毕
- 程序员写博客的重要性!