部落格
沒有人會讀文件(這不是他們的錯)

每一家試圖維護內部文檔或 Wiki 的公司都經歷過相同的生命週期。熱情的啟動、最初的內容創建、貢獻度逐漸下降、漸漸變得陳舊、信任度受損、功能性廢棄。Wiki 依然存在。它仍會出現在搜尋結果中。但沒有人相信它,因為上一次有人按照 Wiki 頁面上的說明操作時,那些說明已經過期了三個月,結果浪費了整個下午的時間。
對於 Wiki 失敗的標準解釋是文化層面的:人們很懶惰、沒有人重視文檔、很難讓工程師動筆寫作。這種解釋是錯誤的,它會導致錯誤的干預措施(強制寫作、文檔衝刺、貢獻遊戲化),這些措施只能帶來暫時的服從,而無法產生持久的改變。
Wiki 的失敗是由於結構性原因,而每種失敗模式都有其結構性的解決方案。
失敗模式 1:內容陳舊
文檔在寫好的那一刻就過期了,因為它們所描述的系統在不斷變化,而 Wiki 卻保持凍結。每一次合併的 PR、每一次架構變更、每一次流程調整,都會讓 Wiki 的準確性降低一點。沒有人負責更新它,即使有人負責,他們也沒有系統性的方法知道哪些頁面受到了哪些變更的影響。
解決方案:能夠從即時活動中自動更新的文檔。當 Wiki 是由 GitHub PR、Slack 討論和會議記錄生成時,它就能保持最新狀態,因為它源自於改變底層系統的同一個源頭。
失敗模式 2:搜尋功能差
大多數 Wiki 工具都是透過關鍵字進行搜尋,這意味著要找到某個內容,必須猜中作者所使用的精確詞彙。「驗證流程」找不到「登入架構」。「部署指南」找不到「發佈手冊」。在經歷兩三次失敗的搜尋後,用戶就會得出該資訊不存在的結論,轉而直接詢問他人。
解決方案:透過含義尋找內容的語意搜尋。你只需描述你正在尋找的內容,系統就會找到概念上相關的結果,而不管使用了哪些具體詞彙。
失敗模式 3:依賴貢獻者的組織結構
每個貢獻者構建頁面的方式都不同,根據自己的習慣命名,並將其歸檔在他們當時認為合理的地方。最終形成的資訊架構反映了二十個不同人的組織習慣,而不是試圖尋找內容之人的需求。
解決方案:自動生成一致的結構。無論是誰生成了底層活動,自動寫作的文檔都遵循標準格式(系統概述、決策記錄、變更日誌)。組織結構由系統決定,而非個別貢獻者。
失敗模式 4:貢獻的額外負擔
撰寫 Wiki 頁面是一項獨立於文檔所描述工作之外的活動。它需要從工作切換到寫作的情境,需要對要包含哪些內容做出判斷,並且知道該頁面需要無限期地維護。在時間緊迫的情況下,這種額外負擔總是會被降低優先級。
解決方案:自動進行的貢獻。當文檔是從工作本身(Slack 對話、PR 描述、會議討論)生成時,貢獻就成了工作的副產品,而不是一項額外的任務。沒有人去寫 Wiki。Wiki 會自己寫自己。
一個運作良好的 Wiki 是什麼樣子的
一個人們真正會閱讀並信任的 Wiki 具有四個屬性:它是最新的(自動更新)、它是可找到的(語意搜尋)、它是一致的(標準化格式)以及它是低成本的(不需要手動貢獻)。大多數傳統 Wiki 都不具備這些屬性,這就是為什麼沒有人閱讀它們的原因。
具有語意搜尋功能的自動寫作文檔同時提供了這四點。其結果是一個透過準確性和實用性贏得信任的知識庫,而不是因為陳舊和搜尋功能差而失去信任。人們閱讀它是因為它有用,而不是因為被要求這麼做。
常見問題
我們應該刪除現有的 Wiki 嗎? 將其保留為歷史檔案,並在其旁邊建立新的自動寫作 Wiki。隨着時間的推移,人們會自然而然地傾向於他們信任的來源(最新的、可搜尋的那個),舊的 Wiki 將成為遺留的參考資料,而不是主要的知識庫。
那些需要人工撰寫的頁面(風格指南、政策)該怎麼辦? 有些內容確實需要人工撰寫:公司政策、品牌指南、哲學性文檔。這些與自動生成的文檔並存。自動寫作系統處理事實性、操作性的文檔。人類則處理敘事性和規範性的內容。
我們如何讓團隊信任新的 Wiki? 信任是建立在準確性之上的。如果人們搜尋 Wiki 五次,並得到五次有用且最新的結果,他們就會繼續搜尋。傳統 Wiki 的信任問題在於準確性會隨着時間的推移而下降。自動寫作的文檔會自動保持準確性,從而維持信任。
相關閱讀:什麼是知識庫、過時的文檔比沒有文檔更糟糕、為什麼 Confluence 沒有用。相關頁面:自動寫作文檔、搜尋、尋找任何內容。
其他部落格文章:

Agent memory vs a shared drive

Can AI agents use Google Drive or Dropbox?

What happens when an AI agent deletes the wrong file

Why AI agents give up searching your files

Why AI agent access should expire

Your agent instruction files are a security risk

When two AI agents edit the same file

Ask your files, don't build a dashboard