writing-docslisted

# 写文档 ## 何时用 - 新建一个库、工具或服务,需要写 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 写文档时爱用"该组件通过注册策略模式实现了可扩展的生命周期钩子机制"这类内部黑话——只有写代码的人知道"策略模式"和"生命周期钩子"在这里指什么。