SuperAPI AI 工具集

technical-writing

写作与研究

查看项目

更新于 10-16 16:28

技能介绍

用途

这是一个技术写作标准技能,目标是让疲惫的工程师第一次阅读就能理解文档。它同时把四层写作规范应用到文档上,并给出三条总原则。

框架与分层

技能要求先为整篇文档选定一种模式,即 Diátaxis 的四种模式之一,一篇文档只使用一种模式:

  • 教程:边做边学,动作加学习。学习者的成功是作者的责任,开篇说明要构建什么而不是要学什么,每一步都要产生可见结果,并说明应该看到什么。
  • 操作指南:面向目标的步骤,动作加实际工作。假定读者有能力,不教学,不跑题,不追求完整,允许分叉与判断,标题按任务命名。
  • 参考:供查阅的事实,理解加实际工作。只描述,不指导,不劝说,不带观点,保持干燥、完整、确定,结构与被描述的对象一致。
  • 解释:理解与原因,理解加学习。单一主题,可脱离产品阅读,标题可前置“关于”,允许出现观点,且只在这里允许。

技能明确要求不要混用模式:教程里不放参考表格,参考里不手把手教学,操作指南里不辩论。需要拆分时用链接。

主要能力

除 Diátaxis 外,技能还包含三层规范:

  • Google 开发者风格:用“你”、现在时对读者说话;说清谁做什么;指令写成命令句;条件放在指令之前;常见情况放前面;不要用“简单”“容易”“快速”这类词;不要预告未来支持的功能;链接要用页面标题或简短描述,不用“点击这里”;标题要带出要点而非仅主题,采用句首大写,每个页面一个 h1。
  • STE 规则:每条指令一个句子,其他句子一个想法;把超过约二十词的指令和超过约二十五词的句子拆开;警告或条件放在它保护的步骤之前;保留“the”和“a”;每个词一个含义一个职责;每个动作固定用一个词;过程写成直接命令;尽量不用 -ing 形式词。
  • Global English 语法:把“only”“not”放在它们修饰的词旁边;拆开长名词串;让每个“it”“they”“this”只指向一个明确对象;不要省略动词;保留“that”这类结构词;序列中重复冠词以防误读;说清“and”“or”连接哪些部分;用句号而非分号;破折号改成新句子;括号内容要么是完整语法单位要么是独立句子;不用“(s)”构成复数;不用斜杠;同一事物全文用同一个名称;不用习语、口语、拉丁缩写和比喻。

技能还提到节奏控制:故意混合句子长短,短句点出要点,长句承载带条件或后果的事实;在模式允许处给出观点,解释模式可以权衡取舍,参考模式保持干燥;要具体而非干瘪。

术语方面,代码库就是词表,写真实的符号、文件、参数或命令名,不自造行话,用开发者会直接说出口的词。首次出现某个命名模式时要说明其含义。

使用方式

资料中说明,以粗体、反引号或 /<name> 形式提到的技能,对应本技能目录旁的 ../<name>/SKILL.md 文件,不带前缀提到的原则对应 ../principle-<name>/SKILL.md,读取该文件并遵循它。多数 pstack 技能仅供用户使用,所以技能工具无法加载它们。

技能还要求把 unslop 技能应用到它涉及的每一篇文档上,该技能负责 AI 词汇、填充词、模糊词、格式痕迹等模式的目录。PR 描述和提交信息也属于写作,除 Diátaxis 外的每一层都适用:PR 正文是一分钟内可读完的简报,不要粘贴 swarm 日志、SHA 列表或指标表格,用链接替代。

产品 UI 字符串不算文档,应使用产品自己的文案规范。代码片段用制表符缩进,写真实路径,每个数量或目录树描述在落地的提交上必须为真,并附上可重新生成它的命令。

适用场景与限制

技能适用于技术文档、操作指南、参考、解释、PR 描述和提交信息等写作。资料同时给出一个改写示例:把一句冗长、被动的配置说明,改写为直接说明 budget.mjs 从 budget.json 读取预算、统计导入 protos 的文件数、超出则 CI 失败,并说明只有调低预算时才运行 --write。

资料未提供收费、价格、平台支持、具体调用步骤或效果数据等信息。