第1课：技术写作概述

什么是技术写作？

技术写作（Technical Writing）是将复杂的技术信息转化为清晰、准确、可理解内容的过程。它不仅仅是"写文档"，而是一门连接创造者与使用者的沟通艺术。无论你是开发者为API写文档，还是产品经理撰写用户指南，技术写作都是你必备的核心技能。

技术写作的核心使命：让正确的人在正确的时间以正确的方式获得正确的信息。

技术写作的三大支柱

技术写作 vs 其他写作

技术写作的常见类型

1. 产品文档

面向最终用户，帮助用户理解和使用产品。包括用户手册、快速入门指南、FAQ等。产品文档的核心衡量标准是：用户能否不求助他人就完成任务？

# 典型产品文档结构
├── 快速入门
├── 安装指南
├── 用户手册
│   ├── 基础概念
│   ├── 核心功能
│   └── 高级特性
├── 常见问题
└── 术语表

2. 开发者文档

面向开发人员，描述系统内部工作原理和接口。开发者文档的关键在于让开发者能快速集成——5分钟跑通Hello World是最基本的要求。好的开发者文档甚至能让SDK成为可选品。

# 开发者文档关键要素
- 快速开始（5分钟跑通Hello World）
- 认证与授权
- API参考（端点、参数、响应、示例）
- SDK集成指南
- 错误处理
- 变更日志

3. 流程文档

描述团队内部工作流程和规范。包括编码规范、发布流程、onboarding指南等。流程文档的核心价值在于减少沟通成本，让新人能快速上手，让老人不重复犯错。

4. 决策文档

记录技术决策的上下文和理由。包括RFC（Request for Comments）、ADR（Architecture Decision Records）等。决策文档最重要的不是记录"做了什么决定"，而是"为什么做这个决定"——以及考虑过但没采纳的方案。

# ADR 模板示例
# ADR-001: 使用 PostgreSQL 作为主数据库

## 状态
已接受

## 背景
系统需要选择主数据库，要考虑数据一致性、查询能力和运维成熟度。

## 决策
选择 PostgreSQL 14.x 作为主数据库。

## 理由
1. ACID事务支持完善，满足金融级数据一致性要求
2. JSONB类型支持半结构化数据，减少表设计复杂度
3. 社区活跃，扩展生态丰富（PostGIS、pg_trgm等）
4. 团队有3年PostgreSQL运维经验

## 后果
- 需要DBA进行vacuum调优
- 读写分离需要额外配置流复制
- 部分ORM的PostgreSQL支持不如MySQL成熟

技术写作的核心原则

原则一：读者优先

每一段文字都要问自己：读者是谁？他们需要什么？他们已经知道什么？读者优先不是口号，而是写作时最重要的思维框架。如果你不知道读者是谁，你的文档就不知道在跟谁说话。

原则二：任务导向

围绕用户要完成的任务组织内容，而不是围绕产品功能。用户不是为了"使用功能"而来的，他们是为了"完成任务"。文档应该从任务出发，功能只是达成任务的手段。

原则三：渐进展开

先给出简单概要，再逐步展开细节。让读者可以按需深入。这就像一本书——先看目录，再看感兴趣的章节，最后才是深入研究附录。

# 渐进展开示例

## 快速入门（5分钟）
三步跑通第一个示例 → 建立信心

## 核心概念（30分钟）
理解系统设计哲学 → 建立心智模型

## 深入指南（2小时）
掌握高级特性与最佳实践 → 生产就绪

## API参考
按需查阅 → 日常开发

原则四：一致性

同一文档中，术语、格式、风格必须一致。建立并遵循样式指南。不一致的文档让读者怀疑内容的可信度——如果术语都不统一，技术细节可靠吗？

技术写作的工作流程

# 标准技术写作流程

1. 规划 ──→ 确定目标、读者、范围
   │
2. 调研 ──→ 收集技术信息、访谈SME（领域专家）
   │
3. 大纲 ──→ 建立信息架构、确定章节结构
   │
4. 起草 ──→ 按大纲填充内容
   │
5. 评审 ──→ 技术评审 + 文档评审
   │
6. 修订 ──→ 根据反馈修改
   │
7. 发布 ──→ 部署到文档平台
   │
8. 维护 ──→ 随产品更新迭代

注意：这个流程不是线性的，而是迭代式的。在实际工作中，你可能需要在调研后回到规划，或者在评审后重新起草。关键是每个阶段都要有明确的输出物。

技术写作的工具链

写作工具

版本管理

技术文档必须像代码一样进行版本管理。使用Git管理文档变更，与代码同步发布。文档没有版本管理，就像代码没有Git——不可追溯、不可回滚、不可协作。

# 文档版本管理最佳实践
docs/
├── versioned_sidebars/
│   ├── version-2.0-sidebars.json
│   └── version-1.0-sidebars.json
├── versions.json
└── docs/
    ├── intro.md          # 当前版本
    └── tutorial.md

技术写作的职业发展

成长路径

初级技术写作者 ──→ 高级技术写作者 ──→ 技术写作负责人
     │                    │                     │
  写好单篇文档         建立文档体系          制定写作标准
  学习工具链          培训其他写作者         推动文档文化
  理解产品           参与产品设计评审        构建工具平台

核心能力模型

写作质量评估

如何衡量技术写作的质量？以下是一个可操作的评估框架：