writing-docs

name	writing-docs
description	写 README/技术文档时使用。让读者快速上手。
category	docs
tags	["文档","readme"]

写文档

何时用

• 新建一个库、工具或服务,需要写 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 同步从文档中删除,不要留注释说"此功能已废弃"三年。
• 对确实暂时没精力更新的部分,在文档顶部明确标注版本号和更新日期。

---

正例 / 反例

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

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

# 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. 运行最小示例:

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": "[e-mail]"}))
print(job.id)  # 输出:job_abc123

---

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

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

## ConfigLoader 类

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

### ConfigLoader.register_validator(fn)

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

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

## 常见用法

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

```python
from mylib import ConfigLoader

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

添加自定义校验

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

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

---

## 自查清单

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