SuperAPI AI 工具集

technical-writing

写作与研究

查看项目

更新于 10-15 22:11

技能介绍

用途:为技术文档提供分层写作标准,让读者一次读懂。四层各回答一个问题:文档属于哪种类型、句子如何称呼读者、每句承载多少信息、句子是否可能被两种方式解读。

主要能力:

  1. Diátaxis 模式选择。一篇文档只用一种模式:教程(行动+学习)、操作指南(行动+工作)、参考(理解+工作)、解释(理解+学习)。教程以“我们”写命令并给出可见结果;操作指南只给步骤、假定读者有能力;参考只描述事实、选项、限制与错误;解释围绕一个真实“为什么”展开,允许观点。不要混用模式,应拆分并链接。
  2. Google 开发者风格。用“你”和现在时;说明谁做什么;指令写成命令句;条件放在指令前;常见情况在前;标题承载要点而非仅主题;链接文字说明去向,不用“click here”。
  3. STE 规则。一句一个指令、一个想法;指令约 20 词、其他句子约 25 词以上拆分;警告或条件放在被保护的步骤前;保留 the 和 a;一词一义;每个动作固定用同一个词;过程用直接命令,不用被动或叙述;少用 -ing 词。
  4. Global English。only、not 紧贴所修饰词;拆开长名词串;it、they、this 指向明确,必要时重复名词;不省略动词;保留 that 等结构小词;用句号而非分号;括号内容须完整;不用斜杠;同一事物全文同名;避免习语、拉丁缩写和隐喻。

三条总则:删掉不干活的词;用短小的日常词;规则让句子变差时另想办法或保持原样。代码库就是词表,写真实符号、文件、标志或命令名。不要发明行话。

节奏:有意混合长短句;一句一个想法不等于一句一个长度;在允许的模式下给出观点;具体优于空泛。

其他:PR 描述与提交信息也属写作,除 Diátaxis 外各层均适用,正文应让评审一分钟内读完,不要粘贴日志、SHA 列表或指标表,改为链接。产品 UI 文案不属文档,应使用产品文案规范。代码片段用制表符缩进,写真实路径与符号,计数或目录树声明须在提交时真实,并附可重新生成的命令。

限制:资料未提供具体安装命令、收费、平台或效果信息;规则细节与词典位于 STE 规范 PDF 中,此处仅为核心原则。