工程 · 2 min read
AI 時代，文件怎麼活下來：大道至簡
AI 讓寫文件變輕鬆，團隊文件卻照樣過期。大道至簡：寫給對的讀者、嚴格規則只交給機器檢查、用固定提醒讓文件一直活著。
文件只有被對的人讀到、用到，才有價值。
故事
大家都同意文件很重要。但這週，誰真的更新過一份文件？
業界很多公司都做不到。我在一場知識管理讀書會上，聽到一個詞：文件墳場。寫了，沒人讀，也沒人改。
我們團隊還做過一個實驗。一個 AI 機器人為每個 pull request 寫一份審查紀錄，存進 repo。四個月後，我們刪掉了 80 份。AI 讓寫文件變得很輕鬆，但文件照樣會爛掉。
為什麼文件總是輸
放進艾森豪矩陣，文件落在「重要但不緊急」這一格。所以每一個 deadline 都會贏過它。
文件不直接帶來營收，所以不被重視。這不是誰偷懶，這是結構問題。
好消息是，AI 正好幫這一格騰出時間。我在第二象限的黃金時代寫過這件事。
寫給誰
- 想讓團隊文件不再爛掉的資深工程師
- 正在把 AI agent 放進開發流程的團隊
- 要整理團隊 wiki，卻不知道從哪裡開始的人
路線圖
1：先想清楚為什麼難
- 寫給誰：只寫讀者查不到的：AI agent 也是讀者。只寫讀者查不到的東西。
- 文件怎麼過期的：80 份 AI 寫的審查紀錄，四個月後全刪。
- 先找痛點再選工具：文件爛掉有三種原因，AI 只解決其中一種。
2：我們自己的規則
- 嚴格規則只給機器能檢查的：機器能檢查的才當規則，其他是習慣。
- 好名字就是不用寫的文件：命名和小符號，本身就是文件。
- 記住去哪找，不是記內容：記住地圖，不用記住每一條街。
3：讓它一直活著
- 讓文件活著：三個提醒，單向流動：三個提醒，加上一個方向的同步。
讀完你會帶走什麼
系列最後的總結篇會把這些整理在一起：
- 串起整個系列的黃金圈：為什麼、怎麼做、做什麼
- 六個帶回團隊討論的問題
- 一個可以試一個月的第一步
從第 01 篇：寫給誰，只寫讀者查不到的開始讀。系列最後是總結篇：把這些帶回你的團隊。
參考來源
- 艾森豪矩陣（Wikipedia）
- Docsie：文件墳場問題
- DIKW 金字塔（Wikipedia）
- TencentDB Agent Memory：四層記憶
- Diátaxis：四種文件類型與兩個軸
- Bullet Journal：符號、索引、每月遷移
- FastAPI：從程式碼產生 API 文件
- GitLab handbook：GitLab 怎麼使用 handbook
- Software Engineering at Google 第 10 章：Documentation（g3doc）
- Elasticsearch：fuzzy query
延伸閱讀： 這個系列接續AI 會搶走我的工作嗎？做一樣的事，拿到更多的 AI 時代故事。