Lidessen's land
← All Skills
npx skills add lidessen/readme --skill doc-writingGitHub ↗
SKILL.mdMarkdown

Doc Writing

这个 skill 做两件事。先从维护者那里拿到只有他们才有的材料：事实、读者是谁、取舍的立场。 再把这些材料写成读者读起来省力的文档。第二步做的事和翻译一样：意思一个字不改，说法换成 读者顺着读下去就能懂的那种。要做好第二步，先要知道读者是怎么读的，以及模型为什么默认 写成读者难读的样子。

读者是怎么读的

读者一次只能拿着几件事。每读一句，他要把这句挂到已经拿着的某件事上；挂得上，这句就变成 他的，挂不上，他要么先悬着，要么自己去补中间缺的那一步。所以一句话应该从读者已经有的 东西出发，只加一样新的。每句都是全新事实的文档，读者没有落点，读几句就丢几句。

读者要在读的过程中判断什么重要。散文里能传递这个判断的信号只有几种：篇幅（作者花了多少 字）、重复（同一件事用后果、例子、数字再说一遍）、位置（一段的第一句）、明说的立场 （“不建议”“最常见的错误是”）。每段差不多长、每句停在同一个抽象层的文档把这些信号抹平了， 读者只能逐句自己判断哪句重要。

认出来便宜，补出来贵。读到一句例子，读者认出它在说上一句的事，用一下或跳过，几乎不花 力气；读到一句省了主语的话、一个当场造的缩略、一个跳过中间步骤的结论，读者要自己把省掉 的部分生成出来。人类维护者的文档删掉“冗余”后其实很短，但复述可以把抽象的话说具体， 也可以唤回前文、加深印象、让读者感知轻重。读者不必每句都接收新事实；适当重现已有内容， 能让他接着往下读。文档很短很密时，这些联系反而可能需要读者自己重建。

读者已经知道什么，决定什么算“已有的东西”。给同一个团队写的设计文档和给外部用户写的 README，同样的事实，该展开的地方不同。所以拿材料的时候要问清读者是谁，这不是形式。

模型为什么默认写成那样

模型没有这些限制。它拿着完整的上下文，不感到每句全新的成本，于是按覆盖来写：一条事实一句， 密度均匀，不分轻重。

它缺维护者才有的材料。没有事实就用模板填（“跨平台支持”“经过生产验证”），没有立场就把 选项对称平铺，没有具体读者就写“无论你是初学者还是专家”。

它受输出预算的压力。系统提示要求简洁，它就省功能词、用箭头和冒号标签代替句子、把规则写成 格言、把段落写成提纲。这最先出现在写作者自己觉得“本来就该短”的地方：规则、标题、列表条目。

它有自己的语域习惯。偏爱的词（赋能、值得注意的是、robust、seamless）、句式（“不是 X 而是 Y”、三件套、句末 -ing 尾巴）、标点（破折号、提示性冒号、满篇加粗）、骨架（总分总、每段一个 加粗小标题、段末总结），还有把一种语言的语法习惯带进另一种。读者一旦认出这是模型写的， 对内容的信任也跟着降。

这四条里，前两条决定文档有没有东西、读者能不能读进去；后两条决定读者认不认得出是模型写的。 四条都要处理，顺序是先前两条。只换词不补材料，骨架还在；只补材料不改表达，读者第一段就出戏。

何时使用

  • 新写或改写 README、Getting started、使用指南、模块说明、设计文档、提案，中文或英文。
  • 用户说文档“不自然”“像 AI 写的”“太空”“太密”，要求修。
  • 从代码、issue、对话记录或用户给的清单整理出一份面向他人的说明。
  • 翻译文档。翻译只做第二步：目标语言按本地写法，术语和标识符不过度翻译；结构、事实和 立场跟原文，不套用重写权限。

博客和个人文章有另一套语气与取舍，不在这里处理；营销页、发布公告以说服为目标，也不在。 从源码生成 API 参考交给工具。单纯纠正语法和错别字不需要读本 skill。

先拿到维护者才有的材料

事实

每一句陈述能指向来源：代码、命令输出、issue、测量结果或用户给的清单。没有来源的数字、 承诺、路线图、性能形容词不写。缺事实时问用户或说明缺少什么依据；只有来源确认未测或未决定 时才这样写，不为填满一节而编。 人类文档明显缺席的部分是正常状态，没有 CONTRIBUTING 就不写贡献指南。

从已给事实推出的结论只走一步，并且读者能用文中已有的事实自己验证。比如已知“每个 worker 各自限速 50 次/秒”和“共 6 个 worker”，写“总量是 300 次/秒”可以；写“这会让 P99 延迟上升” 不行，文中没有支持它的东西。通用领域知识（“TOML 字符串必须加引号”）可以用来解释为什么， 但写成读者能核对的具体陈述，不用它顶替项目自己没做的测量。

读者

具体到“来读这一页的人已经知道什么、来做什么、读完要做什么决定”。README 的读者在判断要 不要用和第一次怎么跑；设计文档的读者是要评审、可能反对的同事；指南的读者手里有一个具体 任务。写之前用一句话说出读者是谁，不确定就问。

事实真实不等于该写。维护者说“读者不需要知道底层用的是什么，我们不想让他们依赖它”，就写 “底层实现不在契约内，可能更换”，不点名。

立场

维护者会写“不建议”“不支持”“这个阈值没有数据支持，先这样定”“如果……就不要用这个”。文档要 替读者做取舍，告诉他哪条路是默认、哪条是例外、什么时候不该用这个东西；不把所有选项平铺成 对称的清单让读者自己挑。

再把材料写成读者省力的文档

用同类文档校准说话方式

仅靠规则提醒，写作时仍可能沿用原来的习惯。写文档的时候，上下文里离得 最近的文本通常是任务说明和模型自己刚写的东西，容易延续同一种腔调。本 skill 对人类文档的描述不能代替文本本身。动笔前完整读一两篇同类、同语言的维护者文档， 从头读到尾，留意问题怎样被解释、解释怎样接到后果。项目自己已经 有人写的文档最好，读者早就习惯了它的口气；没有的话从 human-samples.md 的样本里挑同类型的取来读。读的目的是把那种说话方式带进接下来的写作，不是模仿它的句子， 也不是把那个项目的事实或排版惯例搬过来。已经读过且适合当前任务的文本可以继续用。 离线或链接失效时，用可获得的项目文档校准；作者身份未知就不称它为人类样本。没有合适样本 仍可依据任务材料写作，在交付说明里说清限制，不让寻找样本阻断已有材料足够的任务。

写的时候你是谁

写的时候，你是这个项目的维护者，项目的文档一直是你在写，你面前坐着一个具体的读者，他刚 遇到这一页要回答的问题。你替他做取舍，用他能接上的东西开头，他会追问的事在下一句答掉。 这个身份只借它的说话方式，不借它的记忆：事实仍然只来自材料，材料里没有的你不知道，也不 因为“维护者应该知道”就补出来。它也不是在写博客。试验里让写作者兼有博客作者身份时， 产物变得好读，但也带进了博客的东西：俏皮的小节标题、格言式的收尾、结尾的要点小结、 从人物性格里补出来的细节。这些在文档里是另一种腔调。

写之前先定轻重

动笔前想清读者读完要做什么决定，哪些信息是做决定或完成操作不可缺的。容易误解、后果较大 的地方值得展开，把机制接到后果和例子上；独立参数和简单事实可以短写。篇幅由解释需要决定， 不为了让各节长短不同而拉长或删减。翻译和定向修订沿用原文范围，不借重新分配轻重改变原意。

TiDB 讲 Raft 用了六句：写入要写多数副本；所以丢少数副本也还有最新数据；比如 3 副本写 2 个 就算成功；相比主从同步，延迟取决于最快的两个；所以异地多活成为可能；两地三中心场景下只需 本中心和最近的一个中心写成功。同一篇讲部署只有两句。读者不用读内容就知道作者觉得 Raft 重要。

每句从读者已有的东西出发

先回答读者眼前的问题，再补他理解或行动时还缺的那一步。一个机制让人不知道该怎么做， 就说明后果；文字仍然抽象，就用材料里的场景或例子解释。读者已经能据此行动时，这一段 就可以结束，不必再走一遍“机制、后果、例子”的顺序。几句紧密相关的事实可以连着说， 不必每句都插入解释。例子和数字只能来自已有材料。

一节写出来每句都是全新事实、接不上的时候，有个办法：把它想成一个同事刚在聊天里问了 这一节要回答的问题，先照回复他的样子写，先答他最想知道的，顺着他会追问的顺序往下说。 写完把回复的壳去掉，删掉称呼、开场和“你问的”“简单说”这类口气，内容和顺序留下。回复 天然满足前面说的两条：问题就是读者已有的东西，先答被问的就是轻重。它的代价是回复只答 被问的，写完要对着材料检查有没有该覆盖而没覆盖的事。

要不要删一句话，看它在这里帮读者做了什么。复述即使不增加事实，也可能唤回前文、强调 重要性、加深印象或提醒接下来的操作；同一抽象层的重复、小结和过渡也可以承担这些作用。 不因为“前面说过”或“删后事实仍齐全”就删。只有具体判断它在当前上下文中没有帮助、反而 打断阅读或冲淡重点时，才删改；拿不准时，不为追求信息密度而压缩。

文档的结构由它有什么内容决定

README 第一句说它是什么、给谁用、解决什么问题，用陈述句。然后是读者做决定和上手需要的 信息：安装、最小可运行的例子、反直觉的关键行为、限制与已知问题、什么情况不该用。没有的 东西不留空标题。

设计文档的背景里放真实的问题或事故；方案说清决定了什么；单独一节写考虑过但没采用的方案 和原因；代价、已知问题和没有数据支持的数字明写；未决定的事列出来；实施与验证写具体动作。 小节标题可以直接是主张。

指南按读者任务的顺序组织，每一步给可复制的命令和预期结果。

列表用来枚举本来就并列的东西，比如支持的平台、命令行参数；解释、取舍和因果用段落写。 有几条就写几条，不为了凑成三条加一条，也不为了整齐删一条。条目里写事实，版本、数字、 名字、行为，而不是形容词。

写句子的时候

  • 程度词和泛泛的保守话换成数字、条件和具体行为。保守话要说出是哪个参数、现在是什么值、 为什么不确定、之后靠什么决定。“具体参数可能需要根据实际情况调整”换成“请求超时默认 30 秒。这个值没有测过，是按以前项目的经验定的；上线后如果超时告警多，再考虑调大”。
  • 例子和引文要读者不需要背景就能懂。一句话在原文档里成立，是因为前文定义了术语、读者是 同一个团队；搬进另一份文档时这些支撑就没了。
  • 让一句话里的关系读得出来。机制和例外、原因和结论可以连在一起说；修饰太多、指代不清时 再拆句。句长由内容和目标语言决定，不按样本均值补字或截短。
  • 正文写成读者能接上的句子，不省略必要的主语、条件和连接。标题、参数表和列表中的片段 若能独立理解，可以保留。要求简短时，先删无助于阅读的填充和次要展开，保留有用的复述、操作前提、限制、证据和 用户要求的内容；确实放不下时说明范围或分层展开，不静默少写。
  • 口语程度跟着项目已有的文档走，没有样本就偏中性。不为了显得像人而故意口语化或故意留错。
  • 同一个东西全篇一个叫法。优先用项目和读者社区熟悉的准确术语，不自己造缩略语，也不把 成熟术语一律拆成长解释。比如给服务维护者写“配置热更新”，比含糊的“热加载”更明确； 读者已懂这个概念，就直接用它，需要时再补“修改后须重启”等操作后果。术语是否需要解释， 取决于读者，不取决于它短不短、抽不抽象。
  • 加粗只给读者扫读时必须看到的警告。标题写名词短语，或者读者真会问的问题。
  • 直接从正面说结论。“不是 X，而是 Y”只在 X 确实是读者会有的误解时用。破折号表达的关系 不清时再调整标点或句子；“核心是：”“关键在于：”若只起填充作用，直接说后面的话。
  • 中文按中文的语序和虚词写，英文按英文的冠词、时态和从句写。翻译时术语、命令和社区惯用语 跟随项目和读者的叫法，不为了“全中文”或“全英文”生造译名。两个方向的症状和过度翻译清单见 language-notes.md。

审阅与校对

初稿完成后，再以读者身份通读一遍，并对照来源核实事实、范围、承诺和不确定性。 沿着读者实际操作的顺序检查前提：例如恢复会覆盖数据，备份提醒就应放在恢复命令之前。 发现具体问题才改；表达已经合适时可以保留原稿，不为了显得审过而换词或删复述。 审校通常由写作者完成，不要求独立 Agent、固定轮数或额外审校报告。下面几种看法按需要使用。

检查读者能否从机制接到后果、从说明接到操作。难懂的地方有没有具体场景或例子？代码、数字 和直接描述的场景同样算例子，不必出现“比如”。节长、句长和举例词频只能提示回读的位置， 不能单凭它们判定需要改写；短文、查阅页和并列参数说明也不必刻意制造层次差异。

需要校准语气时，把文稿和读过的同类文档并排读相应的说明段； 样本与观察到的特征见 human-samples.md。逐段问：读者读到这里会问什么， 答了吗？哪些词是形容词而不是事实？哪句是模板填出来的？

仍有表达不自然的地方，按 ai-patterns.md 从内容层到词汇层查对应症状。 命中的地方回到材料问它在替什么占位，补事实或删掉；只换同义词不算修好。同一份文件里的 “不能当判据”表是硬约束：问句标题、“X 是一个……”开头、正文里的“首先……其次”、名词化长句、 举例和复述，人类文档里同样常见，不要为了“更像人”去改。

修订已有文档

只改形式，不改事实、承诺和不确定性。三类分开处理：

  • 形式问题。形容词、口号、模板句、过渡和收尾（“极致性能”“让我们”“Happy coding”）删掉或 换成文中已有的事实；表达层痕迹按 ai-patterns.md 逐条改； 难以理解的电报体展开成句子；翻译腔按目标语言重排；读者缺少理解或行动依据时，补上相关 后果或例子，内容只能来自已有事实，不因段落密度均匀而扩写。动手前先锁住命令、参数名、 数值、URL 和引用原文。
  • 无来源的主张。性能对比、“经过大量生产环境验证”、路线图、支持列表：能在代码或仓库里核实 的去核；核不了的保留原意和原有确定程度，在正文之外列为需要维护者确认的项，不擅自加强、 弱化或换成另一项未经证实的主张。新写文档时，不把缺少证据的主张写成事实。
  • 疑似事实错误单独指出，不替作者下结论。

保留原文的 frontmatter、链接、代码、命令和技术标识符；项目已有的排版惯例（emoji 特性列表、 编号小节）不是本次要修的对象，除非用户要求。

交付

交付文稿本身，正文里不留写作过程或“已去 AI 味”之类的说明。保留支撑主张的来源链接、 引文和版本信息。链接按文档的目标发布位置处理；临时预览文件不改变目标位置，也不要求把 仓库相对链接改成本机绝对路径。实际迁移文档时才按新位置调整链接。另附一段短说明： 哪些常见内容因缺事实被略去或写成未决、哪些推论是自己走的那一步、哪些取舍是替读者做的、 哪些地方需要维护者补充。