Doc Writing

文档写作标准。写或改 README、设计文档、spec、ADR、注释、commit 说明、PR 描述时使用;严谨、清晰、可读、不冗余,功能确定、文档间不互证、形容词需证据、无自我论证、最小有效修改、插入遵循相邻关系。

RedGranite 57f2e7e 2.2 KB Updated

File contents

doc-writing:让人读懂结构,而不是复述实现

何时用

产出任何给人读的技术文本。句子层面另见 plain-language。

硬规则

  • MUST 每份文档有一个确定功能(回答一个问题),不是信息聚合;写不出"这份文档回答什么"就不写。
  • NEVER 两份文档相互重复或相互论证;同一事实一处定义,其他链接。
  • MUST 形容词与程度词带证据(数字、引用、对比),否则删。
  • NEVER 写自我论证("我证明这个功能没必要加");结论直接写,理由只在读者必须知道时写一句。
  • MUST 结构、接口、数据流优先于实现步骤;读者先看懂"是什么、怎么用、依赖什么"。
  • MUST 改文档做最小有效修改:只动需要改的句子,不顺手重写。
  • MUST 新内容插在最相关的已有内容相邻处,不新开孤立章节。
  • MUST 项目 README 有「结构」一节:模块、各自职责、哪些是 core 值得完全理解、哪些是 commodity 只需契约;结构变时同步。

审问清单

  1. 这份文档回答的唯一问题是什么?标题体现了吗?
  2. 哪句话在别的文档已经有了?
  3. 哪个形容词没有证据?
  4. 哪段是在为自己辩护而不是告诉读者事实?
  5. 读者读完能画出结构图、知道怎么调用吗?
  6. 这次修改动了几处?每处都必要吗?

反模式

  • 错误:"本模块采用了高性能、可扩展的架构设计。" → 正确:"单实例 2k req/s(压测见 §5);水平扩展靠无状态 worker。"
  • 错误:README 里再解释一遍设计文档的取舍。→ 正确:README 一句链接到设计文档对应节。
  • 错误:加一个配置项,把整个配置章节重排。→ 正确:在相邻配置项后插一行。

输出要求

文档开头一句说明它回答什么;改动时列出修改位置。

RedGranite/smartskill/tree/main/skills/thinking/doc-writing commit 57f2e7ed57

Frequently asked questions

npx skillmds@latest add redgranite/doc-writing