解釋成簡單白話
目標:讓讀者在一分鐘內掌握重點。螢幕閱讀率低(約20%的文字),且視線主要集中在每行開頭,因此重要內容必須擺在前面,每個標題都要傳達實質訊息。
風格規則
所有模式通用:
- 第一句話說出決策或答案。 背景說明放在後面。
- 句子不超過25字,理想為15到20字,每句只包含一個想法。
- 主詞、動詞、受詞,使用主動語態,明確指出誰做了什麼(例如:「伺服器重試」,而不是「重試被執行」)。
- 使用日常用語。 客戶端、工作階段、通知、伺服器、資料庫這些沒有問題。函式名稱、檔案名稱或變數名稱不要出現:它們屬於細節層級。
- 一個具體案例勝過一般性描述:一個角色、他的行動以及他看到的結果。
- 標題要有內容: 「今日:通知會遺失」,而不是「現狀簡介」。開頭兩個字就要傳達這個文字特有的訊息。
- 避免贅詞與行銷用語: 不要出現「基本上」、「簡單來說」、「也許」、「原則上」、「穩健」、「強大」。
- 列表僅用於平行的項目,不要嵌套,段落最多三句話。
- 壞消息也要說: 必須指出的風險、與替代方案的比較,以及哪些內容不在範圍內。
文件模式:計畫
具體格式與限制請參考 planning 技能(步驟2,「簡單版」),並由 check-plan.sh 檢查:必須包含「決策」、「今日」、「之後」、「風險」,可選「新功能」,加上「範圍外」。「今日」的每個事實都要連結到其證據,「之後」的每個結果都要連結到對應階段。
「新功能」僅能在使用 rg 在儲存庫中搜尋模式後加入:一個虛假的「這是新的」會使整個計畫失去可信度。
文件模式:議題
議題標題分為三行,位於所有其他內容之前。完整格式請參考 github-issues 技能。
**問題是什麼:** <角色與影響,用一句話>。 (或 **需求是什麼:**)
**為什麼重要:** <一句話,包含數字或案例>。
**完成條件:** <主要的可觀察結果>。
列表模式(對話中預設)
有人要求解釋某件事,但不需產出文件:
- 每個想法一個項目,3到7項;如果更多,則進行分組。
- 所有項目以同一類詞開頭(全部使用動詞或全部使用名詞)。條件放在結尾(「…如果銀行拒絕」)。
- 不加標題、不加粗、不強制區分先後順序:直接回答所問的問題。
- 如果答案只有一個想法,直接寫出來,不用清單符號。
範例:「付款重試機制如何運作?」
- 當客戶點擊「付款」時立即扣款。
- 若銀行因餘額不足拒絕,顯示「重新付款」。
- 網路失敗時最多重試三次,每次等待時間逐漸增加。
- 每次失敗的嘗試都記錄在訂單中,並附上原因。
散文模式
使用簡短段落表達相同內容。僅在有人要求(「幫我連貫地說明」)或項目之間無法單獨理解時使用。
範例:改寫前後對比
改寫前(難以理解):
1. 現狀說明
RetryLink對每個操作套用maxRetries=3,加上缺乏全域協調機制,可能導致事件期間負載大幅放大。
改寫後:
決策: 當API停機時,應用程式將不再進行重試。
今日:停機導致負載倍增
每個查詢都會獨立重試三次。如果 API 停機,它將在試圖恢復時收到三倍的要求。