haoxiaobo

从C到C++又到.net, 有一些心得, 和大家交流下...
  博客园  :: 首页  :: 新随笔  :: 联系 :: 订阅 订阅  :: 管理

项目组的文档作风.

Posted on 2005-09-16 11:49  HAL9000  阅读(933)  评论(14编辑  收藏  举报

 

项目组的文档风格问题

 

  叫我怎么说?我们项目组里现在充斥着华而不实的文档作风. 做一件事,这样浮燥,这样不脚踏实地是不行的.

 

  写工作文档,规范严格是重要的,但并不是要把简单问题往复杂了搞,不是要把实际问题抽象化,不是要去找一些意义含糊的词语来表达,不是要把一句话可以说明白的意思用一大段话来说得人人都看不懂!

 

  说到工作文档,我想有下面几点要做好,就够了.

  一.句法不能出问题:

  • 主谓宾一个也不能少.
  • 如果主谓宾的词语不能确切地,无岐义地表达事实,那么必须用确切的定语\状语\补语成分.
  • 不推荐应用定状补定子句.如果需要的定状补成分是一个子句,那么尽可能分句,在另一句中对于需要限制定的语素进行详细说明.
  • 标点符号不能出错,括号内外的标点要遵守括号标点的惯例.

 

  二.用词:

  用词的原则为:

  • 能简单不复杂.
  • 能用常用字词表达,则不用冷僻词.
  • 能用有确切含义的技术名词,则不用俗称或是其他非技术名词.
  • 能具体不抽象.例如要传达"椅子"的概念,就用"椅子"这个词,而不是采用"泛化单式坐恣人体支撑家俱"这样的词,虽然然这样说起来显得很高档.
  • 英文缩写词提供术语解释.
  • 有数值指标的,则不用比较级形容词,如"数据库的容量要达到非常大的容量,在大容量下的性能要在可容忍的限度内."这样的话实际上没有传达信息.而"数据库设计要支持1亿条记录的容量,同在达到1亿条数据时,用身份证号查询记录时,得到结果的时间最长不能大于0.1秒"这样的话就精确定义了信息.

看来我们项目组里有些人需要的不是专业技能, 而是需要补习语文!