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

審查流程

步驟 1：分類文件

類型	關注領域
電子郵件/更新	智慧精煉結構、可掃讀性
提示詞/指令	意圖清晰度、限制條件、格式
技術文件	精確性、術語、層級結構
一般文字	古典風格、流暢度、必要性

步驟 2：檢查智慧精煉結構

針對電子郵件、更新、公告：

✓ 標題：≤6 個強而有力的字？
✓ 第一句：一個關鍵重點？
✓ 「為什麼重要」：清楚表達與讀者的相關性？
✓ 細節：條列式、易掃讀？
✓ 粗體：重點詞彙已強調？

步驟 3：檢查古典風格

原則	紅旗指標
直接的語言	被動語態、名詞化、埋藏的動詞
必要內容	填充詞、重複、顯而易見的陳述
不刻意複雜	過度格式化、巢狀條列、不必要的標題
具體	「各種」、「方面」、「未定義的術語」
一致的術語	同一事物、不同名稱
明確的意圖	缺少目標、模糊的限制條件
以讀者為先	跳躍主題、結論出現在背景之前
可驗證	「似乎」、未經證實的主張

步驟 4：檢查用詞層級的問題

智慧精煉用詞規則：

• 短詞優先：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"

步驟 5：產出審查報告

## 審查摘要

**類型**：[email/prompt/technical/general]
**總評**：[一句話評估]

## 結構（智慧精煉）
- 標題：[✓/✗ + 修正方式]
- 第一句：[✓/✗ + 修正方式]
- 為什麼重要：[✓/✗ + 修正方式]
- 可掃讀性：[✓/✗ + 修正方式]

## 風格（古典）
[列出違規項目，包含位置、問題、修正方式]

## 建議修訂版
[如有要求，提供改進版本]

快速參考：智慧精煉格式

對於電子郵件和更新，使用此結構：

**[6 字標題]**

[一句話：關鍵重點]

**為什麼重要**：[1-2 句說明對讀者的相關性]

**下一步** / **深入探討** / **詳細內容**：
• [條列 1]
• [條列 2]
• [條列 3]

**總結**：[可選的結尾重點]

提示詞專有檢查

目標結構：

Goal: [單一明確陳述]

Constraints:
- [限制條件 1]
- [禁止事項]
- [長度/格式限制]

Output Format: [精確結構]

改進現有提示詞時：

原始問題	修正方式（非刪除）
需求埋藏在散文中	提取 → 明確的條列點
模糊的限制條件（"be careful"）	具體說明（"never exceed 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 — 讓數字有意義，並清晰地呈現它們。