如果您的文檔能自動生成會怎樣？

「自我撰寫的文件」聽起來像是一個矛盾的說法。撰寫文件本應是人類的活動：工程師理解了某些內容，坐下來，並用文字將其解釋出來。認為文件可以自己撰寫的觀點，暗示著其品質會非常糟糕（AI 生成的垃圾內容），或者它會過於膚淺而毫無用處（沒人會讀的自動生成 README）。

這兩者都不是自我撰寫文件在實際應用中的真正含義。

它實際上是如何運作的

其前提是，良好的工程文件所需的核心知識已經存在。它存在於工程師解釋他們修改了什麼以及為什麼修改的 PR 描述中。存在於團隊爭論架構決策、討論折衷方案以及解決設計問題的 Slack 對話中。存在於制定優先級、規劃遷移和審查事件的會議錄音中。存在於 commit 訊息、設計文件和程式碼審查意見中。

這些知識目前是短暫的。Slack 對話串在幾天內就會從螢幕上捲動消失。PR 被合併後就被遺忘了。會議錄音存在一個無人再次訪問的資料夾中。在一個正常的工作週內，知識被創建、分享，然後流失。

自我撰寫文件會在這些知識被創建時將其擷取，並將其結構化為一個持久、可搜尋的維基（wiki），且隨著底層活動的變化而保持即時更新。

這個流程如下運作：

連接您的來源。 GitHub 儲存庫、Slack 頻道、會議錄音、Discord 伺服器。這些是工程知識已經被分享的地方。

系統進行讀取與整合。 當新的 PR 被合併、新的對話發生以及新的會議被錄音時，系統會處理這些內容，提取與工程相關的知識，並將其整合到結構化的文件中。

維基自行維護。 當 PR 改變了系統的運作方式時，關於該系統的文件也會隨之更新。當 Slack 對話解決了一個設計問題時，相關文件會納入該決策。文件之所以能保持最新狀態，是因為它衍生自改變底層系統的相同活動。

工程師審查與完善。 系統產生第一稿。工程師進行審查、糾正不準確之處、添加上下文，並用自動化系統無法推斷的見解來豐富文件。工程師的角色從作者轉變為編輯者，這是一項只需十分鐘的任務，而不是兩小時的寫作課。

輸出結果是什麼樣子

生成的文件是結構化、有引用來源且可編輯的。

結構化意味著它遵循一致的格式：系統概述、API 文件、決策記錄、變更歷史、團隊專屬的維基。格式是標準化的，這意味著無論描述哪個系統，文件都是易於導覽且可預測的。

有引用來源意味著文件中的每個聲明都鏈結回其來源：PR、Slack 訊息、會議時間戳記。閱讀文件的工程師可以點擊進入原始上下文，以驗證任何聲明或獲取更多細節。這就是自我撰寫文件與 AI 生成文本的分別：文件立足於實際活動，而不是從模型的訓練數據中生成的。

可編輯意味著生成的文件是起點，而不是最終產品。工程師可以修改、重組和註釋文件。系統會從這些編輯中學習，進而改進未來的生成內容。

它不是什麼

自我撰寫文件並不是被提示去「為我們的程式碼庫撰寫文件」的 AI 生成文本。那種方法產生的通篇、通常不準確的文字，讀起來就像是語言模型在猜測您的系統可能會做什麼。

自我撰寫文件是從您實際的工程活動中生成的：真實的 PR、真實的對話、真實的會議。輸出結果描述了實際發生的情況，而不是模型認為可能發生的情況。引用來源提供了可驗證性。持續更新提供了即時性。人工審查提供了品質保證。

這種區別至關重要，因為對文件的信任是脆弱的。工程師一旦發現自動生成的文件不準確，他們就會以與不讀已過時的手動撰寫文件一樣快的速度，停止閱讀它們。自我撰寫文件透過可驗證（每個聲明都有來源）和即時更新（文件隨系統變化而更新）來贏得信任。

來源

自我撰寫文件可以從多種來源類型中提取，且隨著連接更多來源，覆蓋範圍會更加完善：

GitHub：PR 描述、commit 訊息、程式碼審查意見、issue 討論。這些擷取了修改了什麼以及為什麼修改。

Slack：設計討論、架構爭論、事件響應對話串、決策對話。這些擷取了未能寫進程式碼中的推理過程。

會議：Sprint 規劃、架構審查、事件檢討會、入職培訓。這些擷取了通常會流失的口頭上下文。

工程管道：專門的工程 Slack 頻道、Discord 伺服器，或其他進行技術討論的溝通工具。

連接的來源越多，文件就越全面，關鍵知識從工具之間的縫隙中流失的可能性就越小。

常見問題解答

生成的文件有多準確？ 準確性因來源品質而異。具有清晰解釋的 PR 描述比單行的 commit 訊息能產生更好的文件。詳細的 Slack 討論比簡短的交流能產生更好的文件。引用系統讓工程師可以透過檢查原始來源來驗證任何聲明，而審查步驟則在不準確的內容被信任之前將其捕獲。

設定需要耗費多少工程時間？ 連接來源通常需要不到一個小時。一旦連接來源，系統就會開始生成文件。與手動撰寫文件通常消耗的每週五個小時相比，持續的審查時間大約是每位工程師每週十到十五分鐘。

我們可以控制系統擷取的內容嗎？ 可以。您可以選擇系統讀取哪些儲存庫、哪些 Slack 頻道以及哪些會議類別。私有頻道、敏感儲存庫和機密會議都可以排除在外。

這會取代 Confluence/Notion/我們現有的維基嗎？ 它可以取代它們，也可以作為補充。自我撰寫文件系統產生結構化、可搜尋的文件，其目的與手動維基相同，其優勢在於它會自動保持最新狀態。現有的維基內容可以與生成的文件並存保留。

延伸閱讀：為什麼工程文件很重要、文件的悖論、為什麼工程師討厭寫文件、自我撰寫文件 vs Confluence。相關頁面：自我撰寫文件、適用於工程團隊。