| name | docs-style-guide |
| description | Apply a clear and consistent technical documentation writing style. Use when writing, revising, or reviewing developer guides, tutorials, how-to pages, or narrative API documentation that should be direct, calm, concise, example-first, and progressively disclosed. |
技术文档写作风格指南
像坐在读者身边的同事一样写：直接、平静、具体，一次只解释一个概念。先让读者看到结果，再解释结果，最后按需补充细节。
语气
- 使用自然、克制的表达，不使用宣传口吻或学术腔。
- 直接对读者使用“你”；与读者一起执行操作或作出判断时使用“我们”。
- 承认复杂性，但不要使用“显然”“很简单”“只需”等贬低困难的表达。
- 删除“本节将介绍”“下面我们来看”等没有提供信息的元话语。
- 少用“强大”“优雅”“灵活”等评价性形容词，直接说明能力、限制或结果。
推荐：
- “我们先看一个最小示例。”
- “如果你需要保留原始顺序，请使用
stable 选项。”
避免：
- “本节将对该机制进行详细介绍。”
- “你只需使用这个强大而灵活的选项。”
信息展开顺序
介绍一个概念时，按以下顺序展开：
- 用一句平实的话说明它是什么或能解决什么问题。
- 尽早给出只包含当前概念的最小示例。
- 紧接着解释读者刚看到的代码、命令或输出。
- 在读者建立基本模型后，再说明默认值、限制、例外或可选方案。
- 只有在确有自然下一步时，才给出具体动作或深入链接。
先写默认情况，再写例外；先写可观察的行为，再写内部原理。不要在第一个示例之前堆叠背景知识，也不要提前引入当前页面尚未铺垫的概念。
示例
- 让示例成为解释的中心，正文只说明示例已经展示的内容。
- 保持示例足够小，删除与当前概念无关的导入、配置和分支。
- 将解释紧邻对应的代码或输出，避免让读者跨越多个段落寻找对应关系。
- 逐一解释不直观的名称、参数和结果，不要逐行复述一眼可见的语法。
- 需要比较多种方式时，使用结构相同的并列示例，让差异容易扫描。
推荐：
- “上面的
computed() 会根据 author.books 生成一个派生值。”
避免：
- 在示例后重新讲一遍与示例无关的完整架构。
- 用长段落逐字复述代码。
句子与用词
- 优先使用主动语态和具体动词，例如“返回”“缓存”“跳过”“抛出”。
- 一句话只承担一个主要信息；条件较多时，拆成列表或分句。
- 首次出现术语时用一句话定义，之后保持名称一致，不为了变化而替换同义词。
- 区分“必须”“默认”“推荐”和“可以”，不要把建议写成要求。
- 给出明确条件，避免“通常”“有时”“在某些情况下”等没有边界的表述。
- 使用读者能直接搜索到的 API、选项和错误名称。
段落与标题
- 每段写 1 到 3 句话，并让第一句承载该段的主要信息。
- 使用能说明读者目标或问题的标题，例如“配置缓存时间”，避免“更多信息”。
- 用列表呈现并列选项、条件、限制和步骤；不要把单个句子拆成列表。
- 将警告、兼容性限制和破坏性操作放在提示块中，不要埋在普通正文里。
- 保持代码块、输出和对应解释相邻。
- 避免连续多层标题后才出现正文。
选择、限制与建议
- 先说明选择标准，再给出建议。
- 同时说明建议适用的条件和不适用的条件。
- 多个方案都有效时，按读者目标描述取舍，不要宣布唯一的“最佳实践”。
- 描述限制时说明影响和应对方式，不只说“注意”或“可能有问题”。
推荐：
- “如果你更在意启动速度，选 A；如果你需要更低的运行时延迟，选 B。”
避免：
链接与收尾
- 使用能说明目标的链接文字，例如“配置缓存”或“查看错误码”，不要使用“点击这里”。
- 直接链接到相关页面，避免“后面我们会讲”这类没有位置的信息。
- 只在章节存在明确后续动作时给出下一步，不要机械地给每节添加收尾句。
- 让收尾简短，避免重复本节已经说明的内容。
常见改写
| 原写法 | 改写方向 |
|---|
| “本节将介绍缓存的相关内容。” | “缓存可以减少重复请求。” |
| “这个选项非常强大。” | 说明该选项具体改变什么，以及何时使用。 |
| “显然，这里只需传入令牌。” | “将令牌传给 token 参数。” |
| “后面我们会详细介绍配置。” | 直接链接到“配置”页面。 |
| “A 是最佳方案。” | 按性能、复杂度或兼容性说明 A 与其他方案的取舍。 |
