# Writing Docs

> 写 README/技术文档时使用。让读者快速上手。

- Skill: `wade-devcode/writing-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wade-devcode/writing-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wade-devcode/writing-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Wade-DevCode (https://skillmd.com/u/wade-devcode)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/wade-devcode/writing-docs

---


# 写文档

## 何时用

- 新建一个库、工具或服务,需要写 README。
- 现有文档与代码脱节,需要更新。
- 接到"补充文档"的任务,不确定该写什么、写多少。
- 写内部技术方案或 API 参考文档。

## 核心规则

### 1. 开头讲"这是什么、解决什么问题、给谁用",30 秒能判断要不要继续读

**规则：** 文档第一屏必须回答三个问题:这个东西是什么、它解决了什么具体问题、目标读者是谁——不废话,不卖关子。

**为什么：** AI 写文档时惯于先铺一大段背景介绍和设计理念,把"这是什么"埋在第三段。读者在 30 秒内判断不了这个东西是不是自己需要的,直接关掉。常见事故:README 开头一段"现代分布式系统面临的挑战……",读到第五段才出现一句"本库用于…"——用户早已离开。

**怎么做：**
- 第一行:一句话说清是什么。`xxx 是一个用于 yyy 的 zzz 工具。`
- 第二段:说清它解决什么痛点,以及不解决什么(边界)。
- 第三段或 badge 区:目标用户(前端?后端?DevOps?)、语言/运行时要求。
- 整个"是什么"部分控制在 5-8 行以内。

---

### 2. 快速开始可复制即用:安装命令、最小示例,真实可跑

**规则：** "快速开始"章节必须包含可直接复制执行的安装命令和最小完整示例,运行后能看到预期输出。

**为什么：** AI 写的"快速开始"常用伪代码或省略关键步骤:用 `<your-api-key>` 占位符但没说去哪里拿,import 路径和实际包名对不上,示例依赖某个环境变量但没说明。读者跟着做一遍跑不起来,信任立刻崩塌。文档最大的用途就是让人第一次能跑通——跑不通的文档比没文档更打击信心。

**怎么做：**
- 安装命令给出完整版本(`npm install xxx@2.1.0` 或 `pip install xxx==1.5.0`)。
- 示例代码能"无脑复制到空项目里跑通",不依赖未说明的前置条件。
- 如果有必填的环境变量或配置,在示例旁边紧接着给出怎么获取/生成的说明。
- 文档发布前自己跑一遍快速开始章节,确认没有步骤缺失。

---

### 3. 结构按读者需求组织(上手→用法→进阶),不按代码结构

**规则：** 文档目录顺序应遵循读者的使用旅程:从快速上手到常见用法到高级配置,不要按照代码文件/模块的组织方式排列。

**为什么：** AI 生成文档时容易"按代码写文档"——每个 class 一个章节,每个方法一条记录,按字母序排列。这是 API reference 的写法,不是入门文档的写法。结果:新用户找不到"我应该先做什么",所有内容平铺在同一层级,没有优先级感。常见事故:一份有 30 个章节的 README,读者需要的"基本使用"在第 17 章。

**怎么做：**
- 固定骨架:`简介 → 快速开始 → 常见用例 → 配置参考 → 常见问题 → 贡献指南`。
- 把 90% 的用户只需要一次的内容(部署、迁移、高级配置)放到"进阶"或单独页面。
- API reference 独立一份,不要混在入门文档里。

---

### 4. 示例胜过描述;术语一致,避免内部黑话

**规则：** 能用代码示例说明的,不用长段文字描述;全文使用统一术语,不造自己发明的词。

**为什么：** AI 写文档时爱用"该组件通过注册策略模式实现了可扩展的生命周期钩子机制"这类内部黑话——只有写代码的人知道"策略模式"和"生命周期钩子"在这里指什么。外部读者完全无法映射到自己的使用场景。而一个具体的代码示例,10 行能传递 3 段文字无法表达的信息量。

**怎么做：**
- 凡是涉及"如何使用",优先给代码示例,文字作为辅助说明。
- 术语首次出现时给一句通俗解释:`钩子(hook)——在特定生命周期节点被自动调用的回调函数`。
- 不用内部代号、项目昵称、公司方言,假设读者是第一次接触这个项目的外部人员。

---

### 5. 与代码同步更新,过期文档比没文档更糟

**规则：** 每次改动影响到 API 或使用方式时,必须同步更新对应文档;过期或错误的文档要删除或标注,不能留着误导读者。

**为什么：** AI 实现新功能时经常忘记更新 README 和示例代码。结果是新用户照着文档里的旧 API 写,运行报错,以为是自己的问题。或者文档里有个"将在下一版本实现"的 `TODO` 留了两年,功能早实现了但文档从没更新。过期文档产生的信任成本比没文档更高——读者不知道哪些是真的,只能全部怀疑。

**怎么做：**
- PR checklist 里加一项:"文档是否需要更新?"(参考 PR 描述 skill)。
- 已删除的功能/API 同步从文档中删除,不要留注释说"此功能已废弃"三年。
- 对确实暂时没精力更新的部分,在文档顶部明确标注版本号和更新日期。

---

## 正例 / 反例

### 反例:开头铺背景、快速开始跑不通

```markdown
<!-- 反例 — 开头废话,快速开始有致命缺失 -->

# MyLib

随着云原生架构的普及,开发者越来越需要高效处理异步任务。
本项目诞生于 2023 年的一次内部黑客马拉松,旨在探索……（三段背景）

## 快速开始

```python
from mylib import Client
client = Client(api_key=API_KEY)  # ❌ API_KEY 哪里来的?没说
result = client.run(task)          # ❌ task 是什么结构?没说
```
```

```markdown
<!-- 正例 — 开头直接,快速开始可复制即用 -->

# MyLib

**MyLib** 是一个 Python 异步任务队列客户端,用于把耗时操作卸载到后台 worker 执行。
适合需要在 Web 请求中异步处理邮件发送、图片压缩等任务的场景。
要求:Python 3.10+,需要自建或托管的 MyLib Server。

## 快速开始

1. 安装:

```bash
pip install mylib==2.3.1
```

2. 获取 API Key:登录 https://mylib.example.com → Settings → API Keys → 生成新密钥。

3. 运行最小示例:

```python
import os
from mylib import Client, Task

client = Client(api_key=os.environ["MYLIB_API_KEY"])  # ✅ 明确说明来源
job = client.enqueue(Task(type="send_email", payload={"to": "a@b.com"}))
print(job.id)  # 输出:job_abc123
```
```

---

### 反例:按模块结构组织,示例少

```markdown
<!-- 反例 — 按代码模块排列,文字描述多,示例少 -->

## ConfigLoader 类

ConfigLoader 类负责从多种数据源加载配置,支持环境变量覆盖、
类型转换、默认值注入及验证回调注册。内部采用责任链模式……

### ConfigLoader.register_validator(fn)

注册一个验证器函数。该函数接受 config dict 并返回 bool……
```

```markdown
<!-- 正例 — 用例驱动,示例优先 -->

## 常见用法

### 从环境变量加载配置

```python
from mylib import ConfigLoader

config = ConfigLoader.from_env()
print(config.get("DATABASE_URL"))  # ✅ 一看就知道怎么用
```

### 添加自定义校验

```python
def must_have_db(cfg):
    return "DATABASE_URL" in cfg

config = ConfigLoader.from_env(validators=[must_have_db])  # ✅ 示例即文档
```
```

---

## 自查清单

- [ ] 文档第一屏能在 30 秒内让读者判断这个工具是否适合自己。
- [ ] 快速开始章节的每一步我都亲自跑过,确认可以从零复现。
- [ ] 文档结构按读者旅程组织(上手→用法→进阶),不按代码模块排列。
- [ ] 关键操作用代码示例展示,没有纯文字描述却没有示例的章节。
- [ ] 没有使用只有团队内部人才懂的术语或代号。
- [ ] 本次代码改动涉及的 API 变化已同步更新到文档。
- [ ] 过时或已删除的内容已从文档中移除,没有留"废弃"标注超过一个版本周期。