工程圈最近愈來愈有一種聲音：文件是過時的遺物。這種論點通常是這樣的：我們正處於由代理驅動的開發時代。如果 AI 代理能即時讀取原始程式碼，或解析 OpenAPI 規格，為什麼還要浪費人類工程師的時間去寫說明文字？反正程式碼變動太快，而人寫的文件一提交就過時了。
這種看法很誘人，也把世界切成黑白兩色。但它完全錯了。
把你真正的「單一事實來源」追求成嚴格決定論，是不切實際的幻想。程式碼和規格只能告訴系統某件事「怎麼運作」，但它們從根本上無法解釋這件事一開始「為什麼」要這樣設計。
意圖落差：為什麼只有程式碼還不夠
即使你是完全為了下游的 AI 代理而開發，原始 API 規格與實際營運現實之間，仍然存在巨大的結構性落差。
代理在模式比對和語法執行上非常出色，但在架構哲學與人類意圖上就沒那麼擅長。我們仍然需要文字來補足脈絡。規格可以定義一個端點、它的參數，以及它的酬載；但它無法捕捉的是，為什麼某個特定的架構取捨會這樣做，或某個舊有特殊案例背後隱含的歷史脈絡。
敘述文字為非決定性系統提供防護欄。即使這些文字最終是被機器而不是人類消化，書面語仍然是傳遞意圖最具槓桿效益的方式。
以爛內容解釋爛內容的危險
這不代表我們要回到手動維護龐大、靜態 wiki 頁面的年代。自動化在這裡仍然有極大的作用。級聯式自動化——也就是文件隨著程式碼變更動態生成——非常強大。
但這裡有個陷阱：用爛內容解釋爛內容，完全沒有用。
如果我們把文件生成完全交給未經把關的 LLM，最後只會得到一個回音室式的循環：幻覺出來的脈絡，在快速變動的程式碼上不斷覆寫。它帶來的是雜訊，不是清晰。
關鍵在於監督。 即使文件完全由機器驅動，人類工程上的監督仍然不可或缺。我們需要做直覺檢查並驗證生成的文字，確保它呈現的是整體脈絡下正確、且高層次的說明。把生成的文件想成 API 本身的一個非決定性表親——非常有價值，但前提是必須嚴格控管。
信任危機與對聲譽的追尋
目前，這個新典範最大的阻礙就是信任。現階段缺乏一個能做「直覺檢查」的文件可信度指標，已經成為人類開發者與自主代理的巨大瓶頸。
在過去的開源時代，我們依賴的是粗略但有效的聲譽代理指標。如果某個儲存庫有 10,000 顆 GitHub 星號、活躍的議題追蹤系統，以及近期仍有提交，你大致可以合理推定這個專案（以及它的文件）是穩定的。
但我們還沒有一套可靠的 AI 時代聲譽系統。當下的全新感，加上自動化指標又非常容易被操弄，讓一切都顯得有些飄忽不定。
下一波開發者工具的重要轉變，不會只是讓代理更快，或讓程式碼生成更乾淨而已。它會是解決聲譽問題——建立一套能自動驗證、評分，並保證我們軟體所依賴知識庫可信度的系統。
在那之前，先別刪掉你的 Markdown 檔。機器仍然需要讀懂字裡行間的意思。
原文出處：https://dev.to/ben/the-myth-of-the-post-documentation-era-39al
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
