📚 A-Level Computer Science: System Documentation Standards | A-Level 计算机：系统文档编写规范
System documentation is a fundamental part of any software project. In the CIE A-Level Computer Science syllabus, candidates are expected to understand the role, structure and standards of both user and technical documentation, and to be able to evaluate the quality of documentation produced for a given system.
系统文档是任何软件项目的基础组成部分。在 CIE A-Level 计算机科学考纲中，考生需要理解用户文档和技术文档的作用、结构与编写标准，并能够评价特定系统所产生文档的质量。
1. What Is System Documentation? | 什么是系统文档？
System documentation is the collection of written, graphical and electronic materials that describe a computer system from its inception through its design, development, testing, deployment and maintenance. It serves as a permanent record of what the system does, how it does it, and how it should be used.
系统文档是描述计算机系统从启动到设计、开发、测试、部署和维护全过程的书面、图形和电子材料的总集。它是系统做什么、如何做以及如何使用它的永久记录。
Documentation can be divided into two broad categories: user documentation, which is aimed at the end users who operate the system, and technical documentation, which is aimed at developers, system analysts and maintenance engineers who need to understand the internal workings of the system.
文档可大致分为两大类：用户文档，面向操作系统的最终用户；以及技术文档，面向需要了解系统内部运作的开发人员、系统分析师和维护工程师。
- User documentation explains 'how to use the system' — installing, operating, troubleshooting.
- 用户文档解释"如何使用系统"——安装、操作、故障排除。
- Technical documentation explains 'how the system works' — architecture, algorithms, data structures, interfaces.
- 技术文档解释"系统如何工作"——架构、算法、数据结构、接口。
2. User Documentation — Purpose and Audience | 用户文档——目的与受众
User documentation is written for the people who will actually use the finished system, such as data-entry clerks, managers, customers or the general public. Its primary purpose is to enable a non-technical reader to operate the system correctly, efficiently and safely without needing to know anything about programming or internal design.
用户文档是为真正使用最终系统的人编写的，例如数据录入员、管理人员、客户或普通公众。其主要目的是使非技术读者无需了解任何编程或内部设计知识，就能正确、高效、安全地操作系统。
Good user documentation is written in plain language, avoids jargon, and uses step-by-step instructions supported by screenshots or diagrams. It should also anticipate common mistakes and provide clear error-recovery guidance.
好的用户文档使用平实的语言书写，避免专业术语，并通过截图或图表辅助分步说明。它还应当预见常见错误并提供明确的错误恢复指导。
- Written in everyday language with minimal technical terms.
- 使用日常语言编写，尽量减少技术术语。
- Structured around tasks ('how do I...') rather than components.
- 围绕任务（"我该如何……"）而非组件来组织。
- Contains screen captures, annotated images and worked examples.
- 包含屏幕截图、带标注的图片和示例。
- Includes a quick-start guide for experienced users.
- 为有经验的用户提供快速入门指南。
3. Contents of User Documentation | 用户文档的内容
The table below summarises the standard sections of user documentation required in a CIE examination context. Candidates should be able to recall these and justify their inclusion.
下表总结了在 CIE 考试背景下用户文档的标准章节。考生应当能够回忆起这些章节并说明其存在的理由。
| Section | 章节 | Description | 描述 |
|---|---|
| Introduction | 引言 | Overview of the system's purpose and scope | 系统目的和范围的概述 |
| Installation Guide | 安装指南 | Hardware/software requirements and step-by-step setup | 硬件/软件要求和逐步安装设置 |
| User Guide / Manual | 用户指南/手册 | How to perform each function; menu-by-menu explanations | 如何执行每项功能；按菜单逐一解释 |
| Tutorial | 教程 | A guided walkthrough of typical tasks | 对典型任务的分步引导演练 |
| Troubleshooting / FAQ | 故障排除/常见问题 | Common problems and their solutions | 常见问题及其解决方法 |
| Glossary | 术语表 | Definitions of terms used in the manual | 手册中使用术语的定义 |
| Index | 索引 | Alphabetical list of topics with page numbers | 按字母顺序排列的主题和页码列表 |
A well-designed user manual should also include a help section accessible from within the application itself, often in the form of tooltips, online help or a 'Help' menu.
设计良好的用户手册还应当包含从应用程序内部即可访问的帮助章节，通常以工具提示、在线帮助或"帮助"菜单的形式呈现。
4. Technical Documentation — Purpose and Audience | 技术文档——目的与受众
Technical documentation is written for the system developers, project managers and future maintenance programmers. Its purpose is to record the internal design of the system so that any skilled software engineer can understand, modify and extend the system even if the original authors have left the organisation.
技术文档是为系统开发人员、项目经理和未来的维护程序员编写的。其目的是记录系统的内部设计，使任何熟练的软件工程师即使原始作者已经离开组织，也能理解、修改和扩展系统。
Unlike user documentation, technical documentation assumes a high level of programming and computing knowledge. It uses formal diagrams, data dictionaries, algorithm descriptions and interface specifications.
与用户文档不同，技术文档假定读者具有较高的编程和计算知识水平。它使用正式图表、数据字典、算法描述和接口规范。
- Audience: programmers, testers, analysts, database administrators.
- 受众：程序员、测试人员、分析师、数据库管理员。
- Purpose: to support debugging, maintenance, enhancement and handover.
- 目的：支持调试、维护、功能增强和系统交接。
- Style: precise, formal, and heavily cross-referenced.
- 风格：精确、正式，并带有大量交叉引用。
5. Contents of Technical Documentation | 技术文档的内容
Technical documentation is considerably more varied than user documentation. The following items are commonly listed in the CIE syllabus and are essential for a complete technical manual.
技术文档比用户文档更加多样化。以下条目常在 CIE 考纲中被列出，是形成完整技术手册所必需的。
| Document | 文档 | Content | 内容 |
|---|---|
| Requirements Specification | 需求规格说明 | Functional and non-functional requirements of the system | 系统的功能性和非功能性需求 |
| System Architecture | 系统架构 | Hardware and software components; network layout; modular structure | 硬件和软件组件；网络布局；模块化结构 |
| Data Dictionary | 数据字典 | Definitions of all data items, their types, sizes and validation rules | 所有数据项的定义、类型、长度和验证规则 |
| Algorithm Descriptions | 算法描述 | Pseudo-code, flowcharts or structured English for key processes | 关键流程的伪代码、流程图或结构化英语 |
| Database Design | 数据库设计 | Entity-relationship diagrams, table schemas, queries and indexes | 实体-关系图、表结构、查询和索引 |
| Interface Specifications | 接口规范 | Input/output formats, protocols, API definitions | 输入/输出格式、协议、API 定义 |
| Test Plans and Results | 测试计划和结果 | Test strategies, test data, expected vs actual outcomes | 测试策略、测试数据、预期与实际结果 |
| Maintenance Log | 维护日志 | Record of all modifications, bug fixes and upgrades | 所有修改、缺陷修复和升级的记录 |
It is important for exam candidates to note that technical documentation is often produced during development, not after it. Version control and date stamping are essential to ensure that the documentation always reflects the current state of the system.
考生应当注意，技术文档通常是在开发过程中生成的，而不是在开发结束后。版本控制和日期标记至关重要，以确保文档始终反映系统的当前状态。
6. Documentation Standards and Guidelines | 文档编写标准与指南
Standards such as those published by the International Organization for Standardization (ISO) and the Institute of Electrical and Electronics Engineers (IEEE) provide a formal framework for documentation. In CIE A-Level, candidates are not expected to quote standard numbers, but they must understand the principles these standards enforce.
国际标准化组织（ISO）和美国电气与电子工程师协会（IEEE）发布的标准为文档编写提供了正式框架。在 CIE A-Level 中，考生不需要引用标准编号，但必须理解这些标准所强制执行的原则。
- Consistency — the same terms, symbols and styles are used throughout.
- 一致性——全文使用相同的术语、符号和样式。
- Completeness — every feature of the system is documented.
- 完整性——系统的每个功能都得到记录。
- Traceability — each requirement can be traced to a design element and a test case.
- 可追溯性——每个需求都可以追溯到设计元素和测试用例。
- Maintainability — documentation itself must be easy to update.
- 可维护性——文档本身必须易于更新。
- Accessibility — documents are organised with headings, tables of contents and indexes.
- 可访问性——文档带有标题、目录和索引，结构清晰。
Standards also specify the use of version numbering. A typical version convention is 'Major.Minor', for example Version 2.1 indicates the second major release with minor patch 1. Each modification must be logged so that changes can be audited.
标准还规定了版本编号的使用。典型的版本约定是"主版本号.次版本号"，例如 Version 2.1 表示第二个主版本加上第 1 次小修补。每次修改都必须记录，以便变更可以被审计。
7. The Role of Documentation in the System Life Cycle | 系统生命周期中文档的作用
Documentation is not a single event; it is produced continuously across the system life cycle. The feasibility study generates a preliminary report; requirements analysis produces the requirements specification; design produces architecture and detailed design documents; implementation produces code comments and programmer notes; testing produces test plans and reports; and maintenance produces change logs.
文档编写不是一次性活动；它在系统生命周期中持续产生。可行性研究生成初步报告；需求分析生成需求规格说明；设计生成架构和详细设计文档；实现生成代码注释和程序员笔记；测试生成测试计划和报告；维护生成变更日志。
The Waterfall model is often cited in documentation discussions because each phase formally ends with the delivery of a document. In contrast, Agile methods emphasise working software over comprehensive documentation, but still require user stories, code documentation and release notes.
瀑布模型在文档讨论中常被引用，因为每个阶段都以交付一份文档正式结束。相比之下，敏捷方法强调可工作的软件胜过全面的文档，但仍然需要用户故事、代码文档和发布说明。
Feasibility → Requirements → Design → Implementation → Testing → Maintenance
可行性 → 需求 → 设计 → 实现 → 测试 → 维护
Each stage outputs its own document | 每个阶段都输出自己的文档
8. Documentation for System Maintenance | 面向系统维护的文档
Approximately 60–80% of the total cost of a software system is spent on maintenance after the system has been delivered. Without adequate technical documentation, maintenance tasks such as fixing bugs, adapting the system to new hardware, or adding new features become expensive, risky and slow.
软件系统总成本的大约 60–80% 花费在系统交付后的维护上。没有充分的技术文档，修复缺陷、使系统适应新硬件或添加新功能等维护任务就会变得昂贵、有风险且缓慢。
Three types of maintenance are recognised in the CIE syllabus:
CIE 考纲中承认三种类型的维护：
- Corrective maintenance — fixing errors discovered after release; requires accurate exception logs and clear code documentation.
- 纠正性维护——修复发布后发现的错误；需要准确的异常日志和清晰的代码文档。
- Adaptive maintenance — changing the system to work with new hardware, operating systems or legislation; requires up-to-date interface specifications.
- 适应性维护——修改系统以适配新硬件、操作系统或法规；需要最新的接口规范。
- Perfective maintenance — adding new features or improving performance; requires algorithm descriptions and design documentation.
- 完善性维护——添加新功能或改进性能；需要算法描述和设计文档。
In every case, the maintenance engineer's first resource is the documentation. If the documentation is missing or inaccurate, the engineer must reverse-engineer the code, which is time-consuming and error-prone.
在每种情况下，维护工程师的第一资源都是文档。如果文档缺失或不准确，工程师就必须对代码进行逆向工程，这既耗时又容易出错。
9. Advantages of High-Quality Documentation | 高质量文档的优势
Candidates are frequently asked to evaluate the benefits of good documentation. The advantages can be grouped into technical, managerial and user-related categories.
考生经常被要求评价良好文档的益处。这些优势可以分为技术、管理和用户相关类别。
| Category | 类别 | Advantages | 优势 |
|---|---|
| Technical | 技术 | Faster debugging; easier to extend; reduced 'bus factor' risk | 更快的调试；更容易扩展；降低"公车因子"风险 |
| Managerial | 管理 | Better project control; clear milestones; easier staff onboarding | 更好的项目控制；清晰的里程碑；更容易的员工入职 |
| User | 用户 | Higher productivity; fewer support calls; greater user confidence | 更高的生产力；更少的支持电话；更大的用户信心 |
For the end user, a poorly written manual can make an otherwise excellent system seem hostile and difficult. For the developer, missing technical documentation can render a system effectively unmaintainable.
对于最终用户来说，编写拙劣的手册会使原本优秀的系统显得不友好且难以使用。对于开发人员来说，缺失技术文档会使系统实际上无法维护。
10. Common Documentation Errors and Pitfalls | 常见的文档编写错误与陷阱
Exam questions often ask candidates to identify weaknesses in a given documentation extract. The following list covers the most commonly tested deficiencies.
考试题目经常要求考生识别给定文档摘录中的不足之处。以下列表涵盖了最常见的受测试缺陷。
- Writing user documentation in highly technical language with unexplained jargon.
- 使用高度技术性的语言和未加解释的术语编写用户文档。
- Failing to update the documentation when the system changes.
- 系统变更时未能更新文档。
- Omitting error messages, recovery procedures or backup instructions.
- 遗漏错误信息、恢复程序或备份说明。
- No version number or date, leading to confusion about which document is current.
- 没有版本号或日期，导致对当前文档产生混淆。
- Using screenshots that no longer match the actual interface.
- 使用与实际界面不再匹配的截图。
- Assuming the reader has prior knowledge that they do not possess.
- 假设读者拥有他们并不具备的先验知识。
A common exam scenario presents a small excerpt of a manual and asks: 'Identify three features of this documentation that make it unsuitable for its intended audience.' Candidates must therefore practise studying documentation from both perspectives — the experienced technician and the novice user.
一个常见的考试情景是给出手册的一小段摘录并提问："识别该文档使其不适合目标受众的三个特征。"因此，考生必须练习从两个视角审视文档——经验丰富的技术人员和新手用户。
11. Documentation in the Context of CIE Exam Questions | CIE 考试语境下的文档考点
In Paper 2 (Fundamental Problem-solving and Programming Skills) and Paper 4 (Further Problem-solving and Programming Skills), documentation questions typically appear in the context of a scenario-based problem. A sample question may ask candidates to 'Explain the purpose of a data dictionary' or 'Suggest what should be included in the test plan for a new module'.
在试卷 2（基础问题解决与编程技能）和试卷 4（进阶问题解决与编程技能）中，文档问题通常出现在基于情景的题目中。样题可能要求考生"解释数据字典的目的"或"建议新模块的测试计划中应包含什么"。
For the paper-based examination, a useful strategy is to memorise the key sections of both user and technical documentation using the mnemonics USERTECH and MAINTAIN:
对于笔试，一个有用的策略是使用助记符 USERTECH 和 MAINTAIN 来记住用户文档和技术文档的关键章节：
USERTECH: U – User guide | S – Setup | E – Examples | R – Reference | T – Troubleshooting | E – Error messages | C – Commands/Controls | H – Help
用户文档：U – 用户指南 | S – 安装 | E – 示例 | R – 参考 | T – 故障排除 | E – 错误信息 | C – 命令/控件 | H – 帮助
MAINTAIN: M – Modules | A – Architecture | I – Interfaces | N – Navigation/Data flow | T – Test plans | A – Algorithms | I – Inputs/Outputs | N – Notes (constraints and assumptions)
技术文档：M – 模块 | A – 架构 | I – 接口 | N – 导航/数据流 | T – 测试计划 | A – 算法 | I – 输入/输出 | N – 注释（约束与假设）
These mnemonics are not official CIE material, but they provide a structured way to recall the full breadth of documentation content under exam pressure.
这些助记符并非 CIE 官方材料，但它们提供了一种在考试压力下系统回忆文档内容全貌的结构化方法。
12. Conclusion — Documentation as an Engineering Discipline | 结论——作为工程学科的文档编写
System documentation is not an afterthought; it is a requirement of professional software engineering. A system without documentation is like a map without labels — it may contain all the information, but it is of little use to anyone who was not present when the map was drawn.
系统文档不是事后考虑；它是专业软件工程的一项要求。没有文档的系统就像没有标注的地图——它可能包含所有信息，但对任何不是地图绘制时在场的人来说几乎没有用处。
For A-Level candidates, mastering documentation standards is not merely about passing an exam; it is about developing the professional habit of recording decisions, justifying choices and communicating clearly — skills that are examined throughout the CIE Computer Science syllabus and valued throughout a career in computing.
对于 A-Level 考生来说，掌握文档编写标准不仅仅是为了通过考试；更是为了培养记录决策、论证选择和清晰沟通的专业习惯——这些技能贯穿 CIE 计算机科学考纲，并在整个计算职业中受到重视。
Remember the golden rule: document as you go, not after the fact. The best documentation is the documentation that already exists when it is first needed.
记住黄金法则：边做边记，而非事后补记。最好的文档是第一次需要时就已经存在的文档。
Published by TutorHao | Computer Science Revision Series | aleveler.com
更多咨询请联系16621398022（同微信）
或截图后用「扫一扫 → 相册」选择本图