用户文档与维护文档

使用程序的用户需要哪些文档内容？

• 前提: 不同用户需要不同级别的文档--偶尔使用者、依赖者、必须修改者;
• 常见缺陷: 大多数文档只提供了很少的总结性内容, 就像描绘了树木和树叶, 却没有一幅森林的图案;
• 必备的九项内容:

项	内容
目的	主要功能是什么, 开发程序的原因是什么
环境	运行在什么机器、硬件配置和操作系统上
范围	输入的有效范围, 允许显示的合法范围
实现功能和算法	精确阐述它做了什么
输入-输出格式	必须确切和完整
操作指令	包括控制台及输出内容中正常和异常结束的行为
选项	用户的功能选项有哪些, 如何在选项间挑选
运行时间	在指定配置下解决特定规模问题所需的时间
精度和校验	期望结果的精确程度, 如何进行精度检测

• 篇幅: 三、四页纸常常就能容纳以上全部信息;
• 时机: 由于它包含了与软件相关的基本决策, 绝大部分需要在程序编制之前书写;

验证程序需要哪些测试用例？

• 随发布的用例: 每份发布的程序拷贝应包含一些可以例行运行的小测试用例, 为用户提供"拥有可信赖拷贝且已正确安装"的信心;
• 更全面的用例（供修改后常规运行）, 按输入数据范围分三类:
  • 针对大多数常规数据和主要功能的测试用例, 是主要组成部分;
  • 数量较少的合法数据测试用例, 检查最大可能值、最小可能值和其他有效特殊数据;
  • 数量较少的非法数据测试用例, 检查边界外的无效输入能否给出正确的数据诊断提示;

修改程序需要哪些内部结构文档？

• 前提: 调整或修复程序需要了解全部细节, 且这些细节已记录在注释良好的列表中;
• 必备的五项内容:

项	内容
结构概述	流程图或子系统的结构图
算法	对所用算法的完整描述, 或对文档中类似描述的引用
文件规划	对所有文件规划的解释
数据流	从磁盘或磁带获取数据或程序处理的序列, 以及每个处理过程完成的操作
修改预案	初始设计中已预见修改的讨论; 特性、功能回调的位置和出口; 作者对可能扩充处的意见; 对隐藏缺陷的观察

• 核心要求: 文档除了描述"事情如何做", 还应阐述"它为什么那样"; 目的是非常关键的, 但即使是高级语言的语法也不能表达目的;

文档应该何时写？

• 用户文档: 绝大部分在程序编制之前书写;
• 自文档化部分: 通过程序结构、命名和格式实现的文档, 必须在书写代码时完成;
• 结构图: 若只使用最高级别的结构图, 通常不会频繁变化, 也可作为注释合并到文档中;
• 总原则: 把文档负担降到最小--文档是前人和我们都未能成功背负的重担;