Documentation

💻 IGCSE ICT 全面复习笔记：文档编制（系统生命周期第 7.5 节）

你好！欢迎来到系统生命周期旅程的最后阶段。你已经完成了对新系统的分析、设计、测试和实施。但且慢——用户怎么知道如何使用它？未来的程序员又该如何维护它？这就是文档编制（Documentation）发挥作用的地方！

在本章中，我们将学习为何完善的文档编制至关重要，并详细解析两种必备的文档类型：为 IT 专家准备的详细“蓝图”（技术文档），以及为用户提供的友好“说明书”（用户文档）。

📜 7.5 什么是文档编制？

文档编制是指通过书面描述、指令和指南，解释 ICT 系统如何工作、如何构建以及应该如何使用。

想象一下拼装一个巨大的乐高城堡：你需要简单的图片指南（用户文档）来完成拼装，而如果你以后需要扩建或更换某个零件，则需要包含每一块砖和连接件的详细清单（技术文档）。

你需要掌握的文档主要有以下两类：

• 技术文档 (Technical Documentation)（面向 IT 专业人员）
• 用户文档 (User Documentation)（面向系统的实际使用者）

重点提示：文档编制能确保系统在原开发人员离开后，依然可以被正常使用、维护和修改。

📝 第 1 部分：技术文档（开发者的手册）

技术文档（通常也称为系统文档）是为那些负责管理、维护和可能修改系统的人员编写的。读者群体包括原始程序员、系统分析师以及未来的 IT 支持人员。

技术文档的目的

其主要目标是提供足够的细节，让一名从未接触过该系统的 IT 专业人员也能理解系统各部分的结构和运作方式。

• 帮助 IT 人员维护系统（保持系统平稳运行）。
• 方便开发人员进行调试（修复错误）或修改（增加新功能）。
• 确保系统在整个生命周期内的一致性和质量。

💪 技术文档的核心内容

这一部分内容较多，我们来拆解一下具体需要包含什么：

1. 系统概述与要求

• 系统/程序的目的：清晰说明软件旨在实现什么（例如：“该系统用于管理库存并自动进行补货”）。
• 系统的局限性：系统不能做什么（例如：“该系统只能处理 10,000 条活动记录”或“它无法计算税费”）。
• 硬件和软件要求：运行和维护该软件所需的最低计算机配置（CPU、内存、存储空间）及操作系统/工具程序清单。

2. 设计与逻辑

• 系统流程图：展示数据如何在整个系统及其各个流程中流动的可视化图表。
• 程序流程图/算法：展示单个程序或模块内部逻辑的详细图表或分步指令。
• 程序清单：使用编程语言（如 Python, C++, SQL）编写的实际源代码。

3. 数据结构与验证

• 文件结构：数据组织方式的详情，包括表名、关系和索引键（如主键 Primary Keys）。
• 变量列表：词汇表，列出所有使用的变量，解释其名称、数据类型（如 Integer, Text, Boolean）及用途。
• 输入格式与输出格式：描述或展示具体输入哪些数据（数据采集表单）以及最终结果如何显示（报告布局）的说明或图示。
• 验证程序：应用于输入的具体规则（例如：范围检查 Range check、长度检查 Length check、校验位 Check digit）。

4. 测试信息

• 样本运行/测试运行：所使用的测试数据示例，记录测试期间的预期结果与实际结果。

📖 第 2 部分：用户文档（操作说明书）

用户文档是为终端用户（End-user）设计的——即那些每天坐在电脑前使用软件完成工作的人。这类文档必须易于阅读，避免使用专业术语，并侧重于实际操作步骤。

如果刚开始觉得很难，别担心！记住，核心区别在于读者。如果你的妈妈或年幼的弟弟妹妹能通过这些说明书操作软件，那就是一份优秀的用户文档！

用户文档的目的

其主要目标是确保用户能够高效、自信地操作系统，而无需频繁向 IT 部门寻求帮助。

• 说明如何操作软件（分步指南）。
• 在用户犯错误或遇到报错时提供帮助。
• 以简明的方式介绍系统的功能。

💪 用户文档的核心内容

用户文档可以有多种形式，例如纸质手册、软件内置的帮助文件或网站/Wiki 页面。

1. 入门指南

• 系统目的：简单明了地解释系统是做什么的。
• 系统的局限性：用户可以期待什么，以及系统无法处理什么。
• 硬件和软件要求：运行软件所需环境的快速参考。
• 如何加载/运行/安装软件：设置并启动程序的步骤说明。

2. 操作指南（如何做）

• 如何保存文件或打印数据：与数据交互的基本必要指令。
• 如何添加/删除/编辑记录：详细的编号步骤，指导用户如何处理其负责的数据。
• 输入格式与输出格式：展示数据采集表单样子以及用户可期待看到哪些报告的示例或截图。
• 样本运行：简单的示例，展示任务成功完成后屏幕应该是什么样子。

3. 问题处理

• 错误消息与错误处理：列出用户可能遇到的常见报错信息（例如：“输入的数据无效”），并给出修复问题的明确指导。
• 故障排除指南/帮助热线：专门用于解决常见问题的部分，通常包括支持人员的联系方式。
• 常见问题解答 (FAQs)：对用户常见疑问的解答。
• 术语表：对软件中使用的任何特定专业术语的简单定义（例如：“查询 Query”是什么意思？）。

📌 技术文档与用户文档的对比

考试经常会要求你比较这两种文档，或者说明为什么某些内容在其中一种文档中是必要的，而在另一种中则不需要。以下是关键区别：

技术文档 vs. 用户文档（快速对比）

• 技术文档：侧重于“它是如何构建的？”
  示例内容：编程语言、文件结构、流程图。
• 用户文档：侧重于“我该如何使用它？”
  示例内容：如何打印、故障排除指南、常见问题解答。

你知道吗？ 许多现代公司正在摒弃传统的纸质手册，转而使用“上下文相关帮助”（context-sensitive help）。当你按下 F1 键或点击问号按钮时，系统会立即弹出与当前界面相关的文档。这在用户文档中非常流行！

***

结语与核心要点

文档编制是连接开发团队与现实世界的重要桥梁。优秀的文档可以节省大量时间、金钱并减少挫败感。在回答考试问题时，请务必先确定受众是谁——是程序员还是客户？这会告诉你哪些成分是相关的。