文件文化:好文件是團隊的第二個大腦

我們曾經是一個靠口傳心授運作的團隊。部署流程在某個人腦裡,金流串接的眉角在另一個人腦裡,「為什麼當初這樣設計」的答案在所有人都忘記的地方。平常沒事,直到有一次關鍵成員休長假,一個例行的部署卡住,全團隊對著螢幕猜密碼放在哪。那天我們損失的不是時間,是對自己的信任。

從那之後,文件從「有空再寫的東西」變成我們的基礎建設。這篇想講的不是「文件很重要」這種廢話,是我們實際怎麼寫、放哪裡、怎麼讓它不腐爛——因為文件最大的敵人不是沒人寫,是寫了沒人更新,最後變成一堆美麗的謊言。

我們寫哪三種文件

不是什麼都寫。寫太多跟不寫一樣,都會讓人放棄閱讀。我們只維護三種:

決策紀錄:每一個架構級的決定——為什麼選這個技術、為什麼這樣設計資料流——寫成一頁短文,講清楚背景、選項、為什麼這樣選。重點是:推翻舊決定時不改舊文件,而是寫一份新的,並在舊的上面標記「已被取代」。這樣三年後的人看得到完整的思考軌跡,而不是一個沒頭沒尾的現狀。
操作手冊:部署步驟、還原流程、對帳方法、常見故障的處理。判斷標準很簡單:這件事如果只有一個人會做,公司就欠一份文件。
交接快照:每個專案維護一份「現在進行到哪、卡在哪、下一步是什麼」的活文件。它救的不只是離職交接,更多時候救的是三週後回到這個專案、忘光一切的自己。

文件放在獨立的雲端硬碟或 wiki,是腐爛的開始——因為改程式的人不會順路經過它。我們的做法是文件直接放在程式碼倉庫裡,改功能的同一個提交順手改文件,審查的人一起審。文件的更新責任屬於改動的人,不屬於某個「負責文件的人」——世界上不存在那個人,指望他就是指望文件腐爛。

好文件是團隊的第二個大腦:第一個大腦會離職、會休假、會忘記,第二個不會。

如果你是發案的業主,這件事跟你更有關。系統交付時,你拿到的不該只是一組網址和帳密,而是完整的文件:架構說明、部署手冊、第三方服務清單。沒有文件的系統,實質上被原廠商綁架了——不是他們故意綁你,是除了他們沒人接得起。哪天合作關係變了,你的系統就變成孤兒。我們在交付條款那篇把這件事講得更細。

順帶講文件的品質標準,一句話:寫給三個月後失憶的自己看。不用文采,不用完整,但要能讓一個有基本能力、對背景一無所知的人照著走完。檢驗方法很簡單——找一個沒碰過這件事的人,照文件操作一次,卡住的每個地方就是文件的洞。我們每次演練都會找到洞,每次都慶幸是在演練時找到,而不是在半夜出事時。

誠實說,寫文件到今天仍然是我們團隊裡最需要自律的事,它永遠不緊急,永遠可以明天再寫。我們的解法是把它綁進流程:沒更新文件的功能不算完成。不靠自覺,靠制度——這大概是唯一有效的方法。