# Doc Writing

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

- Skill: `redgranite/doc-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add redgranite/doc-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/redgranite/doc-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: RedGranite (https://skillmd.com/u/redgranite)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/redgranite/doc-writing

---

# 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 一句链接到设计文档对应节。
- 错误：加一个配置项，把整个配置章节重排。→ 正确：在相邻配置项后插一行。

## 输出要求
文档开头一句说明它回答什么；改动时列出修改位置。