為什麼 Confluence 無法發揮作用（以及什麼才有用）

如果您在工程領域工作了幾年以上，您一定體驗過 Confluence 的生命週期。一個新團隊或一個新專案會建立一個 Confluence 空間。充滿動力的工程師會撰寫初始文件：架構概述、設計文件、流程指南。在最初的幾週內，這個空間看起來棒極了。

然後，維護就停止了。PR 照常交付，卻沒有相應的文件更新。架構的變更沒有反映出來。新加入的工程師發現文件描述的是六個月前存在的系統。資深工程師會警告新進人員「維基（wiki）大部分都過時了」，並建議直接用問的，而不是看文件。Confluence 空間變成了美好意圖的墳墓：結構良好、格式精美的頁面，描述的卻是一個早已不復存在的現實版本。

這並非 Confluence 特有的問題。任何依賴人工編寫和維護文件的系統都會遇到這個問題。Notion 維基也會以同樣的方式過時。Google Docs 累積落差的情況完全相同。GitBook 頁面腐爛的速度也一樣。工具不是問題所在。模式才是。

為什麼人工文件會失敗

人工文件之所以失敗，是因為它需要人類去做無法產生直接、可見價值的工作，而且這種付出是持續性的，而非一次性的。

撰寫文件是一次性成本。保持其最新狀態則是無限期的承諾。每一次衝刺（sprint）、每一次重構、每一次架構變更都會產生文件維護工作，而這項工作永遠不會被優先考慮，因為它不交付功能、不修復 Bug，也不會推動任何人在追蹤的指標。

其結果是，即使是具有強大文件文化的團隊也會持續累積文件債，因為系統變更的速度總是超過文件維護的速度。交付速度越快，文件過時的速度就越快，而文件悖論確保了最需要文件的團隊往往最無力跟上維護進度。

Confluence 的特定設計在某些方面讓情況變得更糟。它的搜尋功能不夠強大，以至於工程師即使在文件存在的情況下也常常找不到。它的編輯介面不鼓勵快速更新，因為與在程式碼文件中打字相比，其頁面編輯器顯得非常笨重。而且它的組織結構依賴於有人主動維護空間結構，這又是另一個沒人會優先考慮的維護負擔。

模式的轉變

替代方案不是更好的維基工具。而是建立一個不同的文件創建模式。

在人工模式中，工程師完成工作，然後在另一個系統中撰寫關於該工作的文件。寫作是首要工作之外的第二項任務，在時間上分離，在情境上分離，並且取決於工程師去做這件事的動力。

在自我編寫模式中，文件是從工作本身生成的。PR 描述變成了系統變更文件。Slack 對話變成了決策記錄。會議討論變成了規劃和架構文件。工程師不需要撰寫文件。系統會從工程師現有的產出中自動編寫文件。

這種轉變至關重要，因為它消除了扼殺人工文件的兩種失效模式：動力問題（工程師不想寫文件）和時效性問題（因為維護未被優先考慮而導致文件過時）。

自動編寫維基的外觀與運作

自我編寫的工程維基是一個結構化、可搜尋的知識庫，能透過連結的來源自我維護。

當 PR 合併時，系統文件會自動更新，反映出每個系統的當前狀態，而不是某人上次記得更新維基頁面時的狀態。

決策記錄是從討論和解決架構選擇的 Slack 討論中自動建立的，從而在保存決策的同時也保留了推導過程。

入職培訓材料能保持最新狀態，因為它們衍生自描述當前系統的相同來源，而不是上一次新員工入職促使某人去更新的歷史快照。

變更歷史是由 PR 和對話編譯而成的，提供了每個系統如何演變以及為何演變的時間線。

文件中的每項主張都連結回其來源，這意味著工程師可以透過點擊進入原始 PR、訊息或會議逐字稿來驗證任何內容。這種引用架構是自我編寫文件與 AI 生成文本的區別所在：文件是基於證據的，而不是基於推論的。

遷移過程

從 Confluence 遷移到自我編寫維基並不需要在第一天就遷移所有現有內容。務實的做法是：

連接您的工程來源（GitHub、Slack、會議）。讓系統開始從當前的活動中生成文件。今後使用自我編寫維基來撰寫新文件。將現有的 Confluence 空間保留為舊有的存檔以供歷史參考，並隨著自我編寫維基成為團隊的主要參考，讓其自然淘汰。

在幾週之內，自我編寫維基將包含從實時活動中生成的最新文件，而 Confluence 空間將包含關聯性逐漸降低的歷史文件。這種過渡是自然發生的，因為工程師會傾向於使用他們信賴的來源，而自動保持最新的來源比需要人工維護的來源能更快贏得信任。

常見問題

我們在 Confluence 的設置上投入了大量資金。我們必須放棄它嗎？ 不用。自我編寫維基負責處理今後的新文件。您現有的 Confluence 內容仍可作為歷史參考進行存取。隨著時間的推移，工程師自然會預設使用最新且更值得信賴的來源，因此無需強制遷移。

其輸出品質可以與撰寫良好的人工文件相比嗎？ 對於事實性文件（系統做什麼、如何變更、決定了什麼），其品質相當甚至更好，因為自動化系統會進行全面的記錄，而人工文件則是選擇性記錄。對於敘事性文件（架構哲學、設計原則、團隊文化），人類的寫作仍然更勝一籌。最好的結果是自動化覆蓋事實性文件，並在其上疊加人工編寫的敘事性文件。

這如何處理衝突的資訊？ 系統利用來源的新鮮度和權威性來解決衝突。昨天合併的 PR 優先於三個月前的 Slack 訊息。當系統無法自動解決衝突時，會標記出來供人工審查。

延伸閱讀： 自我編寫文件解析、 文件悖論、 為什麼工程師討厭寫文件。相關頁面： 自我編寫文件、 適用於工程團隊、 Fabric 對比 Confluence。