工程 · 1 min read
好名字就是不用寫的文件
看到 is_active、MAX_RETRY 就懂，不用文件解釋。小符號和一致的標題格式本身就是文件；一個有 20 種標題前綴的 wiki，代價有多高。
看到 is_active，每個資深工程師都知道它是 bool。看到 MAX_RETRY，大家都知道它是常數。沒人把這寫下來，也沒人需要。
這就是 Bullet Journal 的想法：小符號，大意義。
小符號
| 符號 | 意思 |
|---|---|
| • | 任務 |
| ○ | 事件 |
| - | 筆記 |
| ★ | 額外標記：重要 |
| 索引 + 頁碼 | 在哪裡找，以及順序 |
連清單的種類都有意義。編號清單表示「照這個順序做」。項目符號清單表示「順序不重要」。
我們早就在做
- Pull request：
[TICKET-123][TICKET-124] ci: align some-service ... - Branch：
<name>/TICKET-123/delete-old-harness - ADR：
0001-...，編號同時給出順序和地址
我們只是沒把它叫做規則。
反例：一個沒有共同形狀的 wiki
想像一個很常見的團隊 wiki 產品空間（Notion、Confluence 都一樣），很多公司都有。這個空間裡有 23 個產品資料夾。
- 大約 20 種標題前綴：
[Design Doc]、[FE Design Doc]、[BE Design]、[Note]、[User Flow]等。 - 狀態寫在標題裡，有五種寫法：
(TBD)、(Undone)、[Dep]、[?]、(Deprecated)。 - 會議紀錄五種格式，release note 四種。
- 同一個共用元件，出現在三個產品資料夾。
哪一頁才是最新的？新進成員分不出來。找不到，就等於沒寫。
也有好例子。<Name>'s Handover 有 9 頁，形狀都一樣。看標題就知道內容。
名字不一致，搜尋和 tag 也會跟著分裂，見記住去哪找，不是記內容。名字要多細，看讀者是誰，見寫給誰：只寫讀者查不到的。
一個好名字，就是一份永遠不用寫的文件。
參考來源
延伸閱讀： 看看tag 為什麼跟名字一樣會分裂，回頭讀嚴格規則只給機器能檢查的。或回到系列總覽：AI 時代，文件怎麼活下來