zhichao1208/better-doc

Better Doc

基于两大互补框架审查文档：

• 经典风格（Pinker）—— 清晰、精准、必要
• 智能简洁（Axios）—— 结构、可扫描性、影响力

目标：让文字成为通往意义的透明窗口。简洁即自信，冗长即恐惧。

关键规则：保留实质内容

简洁 ≠ 删除。简化表达，保留含义。

审查现有文档（尤其是提示词）时：

应做事项	不应做事项
将冗长的需求变得更直接	删除看似冗长的需求
压缩啰嗦的解释	移除读者所需的上下文
用具体词汇替换模糊术语	剔除约束条件或边界情况
为清晰重组结构	重组过程中丢失信息

切入任何内容前，先问：

1. 这传达了需求、约束或上下文吗？
2. 删除它会改变结果吗？
3. 我能否用更少的词表达同样的意思，而非直接删除？

特别针对提示词：

• 段落中埋藏的需求 → 提取为显式要点
• 隐含的约束 → 显式说明，不要假设它们很明显
• 冗长的上下文 → 压缩，但如果影响行为则保留
• 示例 → 如果阐明边界情况则保留，如果重复则删除

错误做法：“这段太长，删掉。” 正确做法：“这段包含 3 个需求。重写为 3 个要点。”

核心原则

经典风格（8 条原则）

1. 直接的语言 —— 主动语态、清晰的行动者
2. 仅保留必要内容 —— 删除不能增进理解的内容
3. 杜绝人为复杂 —— 结构服务于清晰，而非修饰
4. 具体胜于抽象 —— 使用具体的、可验证的术语
5. 术语一致 —— 每个概念一个名称
6. 意图明确 —— 目标、约束、输出格式（针对提示词）
7. 以读者为先的顺序 —— 按理解路径组织顺序
8. 可验证的陈述 —— 基于事实和逻辑，而非印象

智能简洁（4 个组成部分）

1. 强有力的标题 —— 6 个词以内，吸引注意力
2. 一个要点 —— 第一句话 = 需要记住的一件事
3. 为何重要 —— 关于此事对读者相关性的背景
4. 深入阅读 —— 可选的细节，以要点形式分块

详细说明请见：references/principles.md

审查工作流

第一步：分类文档

类型	重点领域
邮件/更新	智能简洁结构、可扫描性
提示词/指令	意图清晰、约束条件、格式
技术文档	精准性、术语、层次结构
通用文本	经典风格、流畅性、必要性

第二步：检查智能简洁结构

针对邮件、更新、公告：

✓ 标题：≤6 个有力词汇？
✓ 第一句话：一个关键要点？
✓ "为何重要"：与读者相关性明确？
✓ 细节：以要点形式列出，便于扫描？
✓ 加粗：关键术语已突出？

第三步：检查经典风格

原则	危险信号
直接的语言	被动语态、名词化、埋藏的动词
必要内容	填充词、重复、显而易见的陈述
避免复杂	过度格式化、嵌套要点、不必要的标题
具体性	“各种”、“方面”、未定义的术语
术语一致	同一事物不同名称
意图明确	缺少目标、模糊的约束条件
以读者为先的顺序	话题跳跃、结论先于背景
可验证性	“似乎”、无依据的声称

第四步：检查词汇层面问题

智能简洁的词法规则：

• 短词优先：1 音节 > 2 > 3
• 删除：副词、弱词、模糊词
• 始终使用主动动词

删除此类	保留/替换为
"In order to"	"To"
"Due to the fact that"	"Because"
"At this point in time"	"Now"
"Utilize"	"Use"
"Implement"	"Do" / "Build"
"Facilitate"	"Help" / "Enable"

第五步：报告发现

## 审查总结

**类型**：[邮件/提示词/技术/通用]
**总体评价**：[一句话评估]

## 结构（智能简洁）
- 标题：[✓/✗ + 修复建议]
- 第一句话：[✓/✗ + 修复建议]
- 为何重要：[✓/✗ + 修复建议]
- 可扫描性：[✓/✗ + 修复建议]

## 风格（经典）
[列出违规项，包括位置、问题、修复建议]

## 建议修订
[如需要，提供改进版本]

快速参考：智能简洁格式

对于邮件和更新，请使用此结构：

**[6 词标题]**

[一句话：关键要点]

**为何重要**：[1-2 句关于读者相关性]

**下一步** / **深入阅读** / **详情**：
• [要点 1]
• [要点 2]
• [要点 3]

**底线**：[可选的收尾要点]

提示词专用检查

目标结构：

目标：[单一清晰陈述]

约束条件：
- [边界条件 1]
- [禁止做的事]
- [长度/格式限制]

输出格式：[确切结构]

改进现有提示词时：

原始问题	修复方法（非删除）
需求埋藏在行文中	提取 → 显式要点
模糊的约束条件（“小心从事”）	具体化（“绝不超出 X”）
隐含假设	显式陈述
重复的示例	仅当另一个示例已覆盖时删除
边界情况的冗长解释	压缩，保留规则

定稿前检查清单：

• 所有原始需求仍然存在？
• 约束条件比以前更明确？
• 重组过程中没有丢失任何内容？
• 更短且更清晰（而不是仅仅更短）？

标记：缺少目标、模糊术语（"good"、"appropriate"）、无输出格式。

常见修复

问题	原句	修复后
被动	"Data is processed"	"System processes data"
名词化	"Make a decision"	"Decide"
填充词	"It is important to note"	[删除]
长词	"Utilize"	"Use"
模糊	"Various factors"	"Cost, time, scope"
弱标题	"Update on project"	"Project ships Friday"
埋没要点	[要点前的段落]	[要点在先]

---

相关技能

属于一个致力于可靠、清晰沟通的开放代理技能小家族：

• reduce-hallucination —— 审计 LLM 代理；溯源、引用、弃答。
• better-doc —— 经典风格 + 智能简洁。
• numbers —— 让数字有意义，并清晰展示。