docs
编写能让真实人类愿意阅读的文档。简短、直白,围绕尝试完成真实任务的读者展开。
“为功能 X 编写文档”不是我们的工作。“帮助某人用 X 完成 Y”才是。
分两个阶段工作。首先规划故事:谁读这份文档、他们想要什么、需要多少页面。然后才开始编写。
计划不是私密的。在编写任何页面之前,用户必须看到读者列表并选择语气。
查找文档
→ 阅读相邻页面
→ 第一阶段:读者 + 页面
→ 人物门(在聊天中写出读者列表,然后停止)
→ 语气门(在聊天中写出语气,然后停止) [编写页面时]
→ 加载 simple-english 和 i-have-adhd [编写页面时]
→ 第二阶段:编写
功能计划中的文档影响列表仍需通过人物门。在正式编写页面之前,无需通过语气门或加载写作技能。
何时运行
文档随代码发布。在三个时机运行此技能,而不仅仅是当被要求时。
- 有人要求编写文档。立即编写。
- 在规划仓库中的功能或变更时。在计划完成之前,列出哪些文档是新的、哪些需要更新。此文档影响列表是计划的一部分,与代码变更同等重要。为每个页面指定目标读者。
- 完成实现时。在宣示工作完成之前,编写或更新这些文档。如果一个行为的变更没有附带任何文档变更,则不算完成。
最终页面所需的技能
simple-english 和 i-have-adhd 是前置条件。它们适用于文档页面本身,不适用于此规划对话。
在编写页面内容之前立即加载这两个技能。如果此工具链支持技能工具,请使用它。如果不支持,请从本地技能目录读取每个技能的 SKILL.md。不要仅凭记忆编写页面。
如果缺少任何一个技能,请停止并告知用户。不要在没有它们的情况下编写页面。
它们如何协同工作:
- 此技能负责:页面面向谁、页面拆分、先问题后方案、展示而非叙述、无历史泄漏、禁用字符以及相邻页面结构。
simple-english负责句子本身。使用实用模式。在宣布页面完成之前运行其自检。i-have-adhd负责页面形状:首要操作优先、编号步骤、列表不超过 5 项(将“必须做”与“稍后做”拆分,或拆分页面)、无开场白、末尾有可见的成果。
当从此技能加载 i-have-adhd 时,仅将其应用于文档页面。不要将整个会话切换为 ADHD 模式。i-have-adhd 的持久性部分在此处不适用。
首先查找文档
在编写任何内容之前,先找到文档存放的位置。
- 查找 docs 文件夹。先检查
docs/,再检查documentation/、content/docs/、site/、website/docs/。 - 没找到?询问用户文档应该放在哪里。不要猜测,也不要凭直觉创建文件夹。
- 在新内容附近的相邻位置打开 2 到 3 个现有页面。阅读它们的措辞、结构、前置元数据字段和组件。记录明显的语气作为语气门的候选。暂时不要采纳它。
- 记录站点已使用的组件(步骤、标签页、提示框、卡片、手风琴、代码组等)。不同的站点有不同的组件。
- 复用这些组件来讲述故事。如果站点有步骤组件,就用于演练。如果有标签页,就用于框架变体。如果站点没有这些,就使用纯 Markdown。切勿发明站点没有的组件。
如果没有与即将编写的页面相似的页面,请阅读能找到的最接近的页面并与之匹配。
“匹配相邻页面”涵盖的内容及其不涵盖的内容
匹配相邻页面是关于措辞、结构、前置元数据和组件的:标题是句子大小写还是标题大小写、一个部分获得多少铺垫、哪些组件承载演练、代码示例如何引入、前置元数据字段有哪些。
它不是语气门的替代品。相邻页面可以建议一个默认值,但不能替用户做决定。
它不是复制相邻页面不良习惯的许可。无论周围页面如何,禁用中的每一条以及本技能中的每一条规则,在你编写的内容中仍然适用。一个充满长破折号的现有页面并不为再添加一个提供许可。
所以:切勿以“其他页面也这么做,所以我也这么做”为由,违反本技能所述的任何规则。如果现有页面违反了规则,并且你认为应该将整个文档集调整一致,那是一个需要向用户提出的单独的清理工作,而不是通过默默匹配违规行为来掩盖的问题。
第一阶段:规划故事
在开始编写任何内容之前,先做这件事。
- 列出谁阅读这份文档以及每个读者想要什么。一个在 React SPA 上构建的人、一个在服务端渲染应用上构建的人、一个只想快速演示的人、一个扩展内部功能的人。不要只停留在第一个读者。
- 为每个读者编写一个用户故事:“作为一个 X,我想要 Y,以便 Z。”
- 将故事转化为页面。一个旅程就是一个页面。不同的旅程是不同的页面。一个具有三个真实旅程的功能应该是三个页面加上一个简短概述,而不是一个巨型页面。
- 确保每个读者都有对应的路径。一个没有对应页面的读者就是计划中的一个漏洞。为他们添加一个页面或路由。
页面拆分来自此步骤。不要跳过它。
门禁:展示人物角色
提问工具(AskQuestion、ask_user_question 及类似形式)不会将其负载显示在用户阅读的聊天中。仅调用这些工具之一的回合将无法通过此门禁。用户被要求在他们看不到的列表中做出确认。
在步骤 4 之后,编写一条正常的聊天消息。即使同时调用了提问工具,消息正文也是必需的。消息包含:
- 每个读者,作为用户可以快速浏览的独立短块:
- 读者的名称。
- 一个用户故事:“作为一个 X,我想要 Y,以便 Z。”
- 你将为他们编写的页面。
- 一个问题,写在同一消息中:确认、删除一个读者或添加一个。
提问工具是可选的。仅在该列表已经存在于聊天消息中之后才调用它。该工具仅询问简短的选择(确认、删除或添加)。不要将读者名称、故事或页面放在工具内部。如果该工具将是该回合的唯一输出,请不要调用它。改为编写消息。
然后选择一条路径:
默认:停止。 此消息即为整个回合。结束回合。不要编写文件。不要开始第二阶段。不要说你将继续,除非用户反对。
跳过等待:在本回合中继续。 仅当以下条件之一成立时使用此路径:
- 本次对话已经获得了用户对此人物列表的确认。
- 用户说了“使用合理的默认值”、“直接写”或“不要问问题”。仍要在本回合展示列表,然后继续。
- 更改是一个极小的副本编辑:打字错误、损坏的链接、代码围栏语言或事实修正。没有新页面、新章节或旅程重写。
在此路径上,不要结束回合。展示列表之后(或极小的副本编辑之后,没有列表的情况下),继续下一步。
以下情况不跳过:
- “读者很明显。”
- “用户要求编写文档,所以他们不想被提问。”
- “我已经在计划中提到了他们。”
- “只有一个读者。”
- “这是实现功能的一部分,继续吧。”
- “提问工具会向他们显示列表。”它不会。列表放在聊天中。
编写文档正是此门禁存在的原因,而不是跳过它的理由。
少即是多:拆分,不要塞满
不要强迫将数千个字塞进一个页面。长页面会隐藏答案。
当一个主题有多个角度时,为每个角度单独写一个短页面,并将它们链接起来。读者先看到概览,然后点击进入他们确切需要的部分。
例如,一个关于“工具中断”的功能:
糟糕:一个页面
interrupts.md (概览 + 简单案例 + 多个中断 + 自定义,全部塞在一起)
好:一小套链接的页面
interrupts/index.md 它是什么,何时使用,外部链接
interrupts/basic.md 一个中断,从开始到结束
interrupts/multiple.md 一个流程中的多个中断
interrupts/custom.md 构建你自己的中断
每个页面都很简短,只做一件事。概览页面将它们串联成一个故事。
门禁:询问语气
此门禁位于第一阶段和第二阶段之间。在编写任何页面之前运行它。不要将其嵌套在第二阶段内部。
相邻页面可以建议默认值,但不能替用户做决定。
编写一条正常的聊天消息。即使同时调用了提问工具,消息正文也是必需的。消息包含:
- 你从相邻页面推断出的语气,用一行描述(有多正式、有多少铺垫、是否使用第二人称)。
- 一个问题,写在同一消息中:使用该语气、更随意、更正式,或用户指定其他语气。
提问工具是可选的,并且仅在那一行描述已经在聊天中之后出现。该工具仅询问简短选择。不要将推断的语气只放在工具内部。仅调用工具的回合将无法通过此门禁。
然后选择一条路径:
默认:停止。 此消息为整个回合。结束回合。不要编写页面内容。
跳过等待:在本回合中继续。 仅当以下条件之一成立时使用此路径:
- 本次对话已经获得了用户的语气选择,包括明确的“匹配现有页面”。
- 用户说了“使用合理的默认值”、“直接写”或“不要问问题”。仍要用一行陈述推断出的语气,然后继续。
- 极小的副本编辑,与人物门相同的例外。
在此路径上,不要结束回合。在陈述语气之后(或极小副本编辑之后,无问题的情况下),继续到第二阶段。
以下情况不跳过:
- “我可以从相邻页面看出。”
- “站点已经有了统一的风格。”
- “对于参考页面,语气不重要。”
- “我会匹配相邻页面并在之后提及。”
第二阶段:像人类一样编写
在人物门通过、语气门通过,并且加载了 simple-english 和 i-have-adhd 之前,不要编写页面内容。
语气门是上面的标题。先运行那个门禁。然后加载这两个技能。然后编写。
可读性是首要目标,高于一切。
- 保持易于消化。没有文字墙,没有大段落。将想法分解成小块。提供完成工作所需的最少信息量。
- 句子遵循
simple-english(实用模式)。不要内联使用较弱的替代品。 - 保持 Markdown 轻量。列表很好。每行都用粗体标题则不好。让文字本身承载页面。
- 优先使用纯 ASCII 和普通键盘字符,而不是花哨的图形符号。按照人类打字的方式编写。
- 使用第二人称,行动优先。从读者现在有什么以及最后会得到什么开始。不要以“在本指南中,我们将探讨...”开头。直接开始。
- 用
i-have-adhd塑造页面:第一行是读者可以做的事情,多步骤工作使用编号,长度超过 5 的列表被拆分,页面以可见的成果结束。
以问题为先,然后解决它
每个页面都应以读者遇到问题的方式来开头,用他们自己的语言,在任何 API 之前。点明他们所处的困境。然后用一两句话说明该功能如何解决。之后才进入技术部分和代码。
先看到问题的读者能在几秒内知道他们是否在正确的页面上。而先看到 API 签名的读者必须反向工程才能知道它是干什么的。
“如何做”部分的第一行是下一个操作(来自 i-have-adhd)。但问题仍然放在前面,让他们知道他们在正确的页面上。
糟糕:
调用 useInterrupts() 并传入一个解析器。解析器在事务内部对每个待处理项运行一次...
好:
某些工具调用不应该在没有人类明确同意的情况下运行:比如移动资金、删除数据。中断会暂停运行以等待该决策,然后从暂停处继续。下面介绍如何为工具设置一个审批门禁:
[代码]
指南的顺序是:问题、一行修复方案,然后是“如何做”(步骤、片段、API)。将问题控制在一两句话内,而不是一篇背景论文。代码展示了如何解决问题,因此不要先长篇叙述解决方案。
展示,而非叙述
不要用四个段落来解释一个句子加一个代码块就能展示的内容。读者理解差异对比或代码片段比理解散文更快。
糟糕:
三个段落描述了配置对象如何接受一个中间件数组,每个槽位的作用,以及排序的工作方式。
好:
将你的中间件添加到 `middleware` 数组中。顺序从上到下运行:
const app = createApp({
middleware: [auth, logging],
})
一个可运行的好例子胜过一页描述。每个代码示例在被复制时必须能够运行,不需要靠想象力来填补空白。
列表化任何列表式内容
一旦一个句子涉及多个项目、选项、存储、标志或步骤,就应将其转换为列表。不要用逗号和分号将它们串成一个段落。扫描项目符号列表的读者能在一秒钟内找到自己的目标。而在段落中,他们必须阅读整个段落才能知道它是否与自己有关。
判断信号是:一个句子提到两个或更多东西,并对每个东西说了些什么。将其拆分成每个东西一个项目符号,每个项目符号一两句话。
糟糕:
每个存储是独立的。只需提供你需要的那些。对于聊天:`messages` 用于对话记录,`runs` 用于运行生命周期,`interrupts` 用于持久性审批(需要 `runs`),`metadata` 用于带命名空间的键值状态。对于生成:`generationRuns` 用于运行生命周期,加上 `artifacts` 和 `blobs` 来保存生成的字节。
好:
每个存储是独立的,所以只需提供你需要的那些。
对于聊天:
- `messages`:对话记录。
- `runs`:运行生命周期。
- `interrupts`:持久性审批。需要 `runs`。
- `metadata`:带命名空间的键值状态。
希望对您有帮助,如果还有其他问题,请随时提出。
对于生成:
- `generationRuns`:运行生命周期。
- `artifacts`:生成的作品。
- `blobs`:保存的二进制大对象。
让用户赢
读者读完时,他们应该完成了某事:运行了一个命令,看到了一个不同的行为,或理解了一个概念足以自己尝试。页面不能在悬而未决的地方结束。如果指南在代码示例后没有明确的结尾,添加一个总结性的体验:运行脚本,看到输出,知道它有效。
好:
运行 `npm run dev` 并打开 http://localhost:3000。你应该会看到一个带有“欢迎”消息的页面。打开 `app/page.tsx` 并将文本更改为“你好,世界”。保存后浏览器会自动刷新。
禁用
这些规则适用于你编写的所有内容,无论周围页面如何。如果现有页面违反了这些规则,则匹配相邻页面规则不适用。
- 无历史泄漏:不要编写仅当读者读过另一页才理解的文档。每个页面都应该是一个独立的入口点。交叉引用是可以的。前提式文档是不可以的。
- 无长破折号:优先使用短破折号或空格的破折号。不要用
—(长破折号)。–(短破折号)在英文中表示范围(例如第 3–5 页)或连接复合词更长结构中的名称。在其他任何地方,使用-作为破折号,带或不带空格。如果上下文需要非连字符的破折号(例如某些正式德语文本),则短破折号可能是合适的。但始终优先使用破折号的两边都空格的连字符,而不是长破折号。绝不使用长破折号。 - 无尽头的列举:如果必须列出多于 5 项,则将其分组。
- 无表情符号:不要在文档正文中使用表情符号。标题、警告框或代码注释中也不允许。没有任何例外。
- 无惊叹号:除了代码字符串中自然出现的情况外。文档不应该表现出兴奋;它应该只是陈述事实。
- 无非 ASCII 字形:不要使用
×(乘号)、→(箭头)、·(中间点)或除标准拉丁字母(包括带重音符号的常见欧洲字母,如果需要的话)及英语和代码通常使用的标点符号之外的任何符号。 - 无“Please”:除非你在编写一个确实需要礼貌才能理解上下文的系统的对话框文本,否则不要用“please”。文档是工具,不是正式信件。
- 无“Note that” 或变体:如果一件事值得注意,就直接陈述它。不要说你在陈述它。
- 如果东西有效,不要写“simply”:
simply暗示读者如果觉得困难就做错了。它隐蔽地责备。只需给出指令。
关于实施的指导
提供的是“内容”,而不是页面。
- 在需要时使用 Markdown 围栏代码块。不要为每一行中出现的每个设置一个代码块。
- 代码围栏中的语言提示:始终包含语言(例如
typescript、python、bash)。如果只是通用文本且没有指定,使用text。 - 有限使用表格,仅当表格比较列式数据时使用。不要用表格进行布局。
- 在链接中优先使用描述性文本,而不是“这里”或“链接”。
- 如果可以,保持访问入口无目录状态。如果页面有一个内部目录,仅在确实有助于导航时包含它。不要只是因为你认为它应该有一个就添加一个。
终端输出作为内容
当编写 CLI 文档时,终端输出($ 提示符、命令、输出)应该是 bash 代码快照。不要在单独的快照中重复输出。
$ npm init -y
$ npm install jotai
Wrote to /Users/me/project/package.json:
{
"name": "project",
...
}
这包括对现有文件所做的可见更改的展示。
编写稳固的标题
标题回答“这个部分是关于什么的?”。在标题中至少包含一个来自内容的名词,而不是模糊的代词。
不好:
它是如何工作的
The example above calls useInterrupts()……
好:
中断如何工作
The example above calls useInterrupts()……
标题是目录中扫描的内容。如果它是模糊的,读者无法判断它是否与自己的问题相关。
特殊部分
故障排除
如果你的主题位于相关主题的集合中(例如一个包中的多个功能,一个 SDK 中的多个部分),创建一个 troubleshooting.md 页面。保持简短:问题作为问题(## 标题),然后简短答案。一个页面,几个问题,没有废话。
如果单一主题的页面(例如单个功能)自然导致一个常见的陷阱,在该页面的末尾包含一个警告块。只有当它是一个常见的问题时才这样做。
限制
如果某个功能不能做某个重要的事情,或者存在重大的指针限制(例如只有前 10 页,仅适用于 Node.js,仅限自托管),将其作为警告块放在页面顶部附近。不要将其埋没在页面底部或放在单独的页面中。
变更日志
如果你的文档集中包含一个 CHANGELOG.md,保持简短:仅列出值得注意的变更,而不是每个提交。在包含变更日志的文档集中,每个页面可以在底部有一个## 版本 部分,包含该特定功能的最近变更。
最终产品,作为单个字符串返回。