软件技术文档撰写要求

作者：龚云卿 2006-5-30

1  针对性

   文档编制以前应分清读者对象，按不同的类型、不同层次的读者，决定怎样适应他们的需要。    
   ① 对于面向管理人员和用户的文档，不应像开发文档(面向软件开发人员)那样过多地使用软件    
    的专业术语。 难以避免使用的词汇，应在文档中添加词汇表，进行解释。    
   ② 开发文档使用的专业词汇未被广泛认知的，应添加注释进行说明。    
   ③ 缩写词未被广泛认知的，应在其后跟上完整的拼写。    
        
2  正确性 

   ① 没有错字，漏字。    
   ② 文档间引用关系正确。    
   ③ 文档细节(Title/History)正确。    
        
3  准确性

   ① 意思表达准确清晰，没有二义性。    
   ② 正确使用标点符号，避免产生歧义。    
        
4  完整性 

   ① 意思表达完整，能找到主语、谓语、宾语，没有省略主语，特别是谓语。    
   ② 一句话中不能出现几个动词一个宾语的现象。    
   ③ 不遗漏要求和必需的信息。    
        
5  简洁性 

   ① 尽量不要采用较长的句子来描述，无法避免时，应注意使用正确的标点符号。    
   ② 简洁明了，不累赘冗余，每个意思只在文档中表达一次。    
   ③ 每个陈述语句，只表达一个意思。    
   ④ 力求简明，如有可能，配以适当的图表，以增强其清晰性。    
        
6  统一性 

   ① 统一采用专业术语和项目规定的术语集。    
   ② 同一个意思和名称，前后描述的用语要一致。    
   ③ 文档前后使用的字体要统一。    
   ④ 同一课题若干文档内容应该协调一致，没有矛盾。    
        
7  易读性 

   ① 文字描述要通俗易懂。    
   ② 前后文关联词使用恰当。    
   ③ 文档变更内容用其他颜色与上个版本区别开来。    
   ④ 测试步骤要采用列表的方式，用1)、2)、3)…等数字序号标注。