第4章 · 技术文档写作
受众分析 · 术语规范 · 步骤清晰
技术文档写作是连接开发与用户的桥梁。本章聚焦三大核心：受众分析、技术术语使用规范、步骤说明的清晰表达。掌握这些技能，让文档既专业又易读。
4.1 受众分析
明确读者身份、知识水平与使用场景，是技术文档写作的第一步。不同受众需要不同的信息颗粒度与表达方式。
关键问题清单：
- 读者是开发者、运维还是业务人员？
- 他们熟悉哪些术语？是否需要背景介绍？
- 文档的使用场景：快速查阅、学习入门还是故障排查？
4.2 技术术语使用规范
术语一致性是专业性的基石。同一概念在全文中应使用同一名称，避免混淆。首次出现时建议给出定义或链接至术语表。
| 不规范用法 | 规范用法 | 说明 |
|---|---|---|
| “点击按钮” / “按下按钮” 混用 | 统一为“单击”或“点击” | 保持动词一致 |
| “API” / “接口” 随意切换 | 首次写明“API（应用程序接口）”，后续统一用“API” | 避免歧义 |
| “登录” / “登陆” 混用 | 使用“登录” | 遵循行业规范 |
💡 最佳实践： 建立项目术语表（Glossary），并在文档开头或附录中提供。例如：“本指南中，‘实例’指代云服务器实例，而非本地虚拟机。”
4.3 步骤说明的清晰表达
操作步骤必须可复现、无歧义。推荐使用有序列表，每个步骤只包含一个动作，必要时补充预期结果或截图（此处以SVG示意）。
✅ 步骤编写原则
- 动词开头：如“打开终端”、“输入以下命令”。
- 唯一动作：不要在一个步骤里混合多个操作。
- 提供反馈：说明执行后的预期输出或状态。
- 代码与命令行：使用独立代码块，并标明语言。
# 示例：安装 Node.js (Linux)
sudo apt update
sudo apt install -y nodejs
node --version # 预期输出: v18.x.x对比：不清晰 vs 清晰
| 不清晰 | 清晰 |
|---|---|
| 配置数据库连接，修改配置文件。 | 1. 打开 config/database.yml。2. 将 host 值改为 db-prod-01。3. 保存文件并重启服务。 |
本章小结
技术文档写作的核心在于“以读者为中心”。通过细致的受众分析、严格的术语规范以及步骤的清晰拆解，可以大幅提升文档的可用性与专业度。下一章将深入用户手册的编写技巧。