為什麼工程師討厭寫文件（以及為什麼他們是對的）

如果你曾試圖讓工程團隊撰寫更多文檔，你一定知道那會是什麼情況。在命令下達後會有一小段配合期，創建或更新了幾個 wiki 頁面，但不到一個月，團隊又回到了先前的基準線。文檔倡議最終加入了那些出發點良好卻未能堅持下去的流程行列中。

管理層的標準解釋是，工程師對文檔抱持懶惰態度，或者不了解其重要性。這種解釋是錯誤的，且基於此種觀點制定的政策所產生的倡議，會因同樣的結構性原因而一再失敗。

工程師之所以抗拒文檔，是因為他們的反對意見是正確的。

真正的反對意見

上下文切換成本高昂。 撰寫散文與編寫代碼使用的是不同的認知模式。從調試或架構所需的緊密、邏輯性思維，切換到文檔所需的解釋性、關注受眾的思維，其消耗精力的方式是無法在工時表上體現出來的。大多數工程師表示，上下文切換的成本比撰寫本身還要高：在 wiki 頁面上花費 30 分鐘後，需要 20 分鐘才能重新進入代碼狀態。

感覺地位低下。 在大多數工程文化中，交付代碼具有很高的地位，而撰寫關於代碼的文檔則不然。沒有人會因為對 wiki 的貢獻而獲得晉升。沒有人的績效評估會強調其架構文檔的質量。激勵機制告訴工程師，文檔次於構建，而他們對這種激勵做出了理性的反應。

他們知道幾週內文檔就會過時。 這是大多數管理者忽視、而大多數工程師感受最深的反對意見。一位工程師在經歷了自己精心編寫的架構文檔，在經過幾次衝刺（sprints）的變更後就變得不準確時，就會明白撰寫文檔的努力半衰期很短。理性的反應是減少對快速衰減之物的精力投入，而不是增加。

受眾不明確。 這些文檔是給誰看的？未來的工程師？已經了解系統的現有團隊成員？產品經理？根據受眾的不同，合適的詳細程度、框架和技術深度是完全不同的。在受眾不明確的情況下，工程師要麼寫得不對路，要麼因為這種含糊不清讓任務顯得無邊無際而什麼都不寫。

為什麼激勵不是解決辦法

了解這些反對意見是結構性的而非積極性問題，會改變解決問題的方法。

激勵方法（強制要求文檔、將文檔加入衝刺要求、將貢獻遊戲化）只能帶來暫時的配合，但無法解決工程師抗拒的底層原因。上下文切換依然昂貴，地位層級未曾改變，文檔也依舊會過時。

真正有效的方法是解決結構問題，而不是解決積極性問題。

將工程師移出撰寫環節。 自撰寫文檔從已經在進行的工程活動中生成結構化文檔：包括PR 描述與提交信息、討論決策的 Slack 對話，以及辯論架構的會議。工程師的貢獻是工作本身，而文檔是副產品，而不是額外的任務。

讓文檔自動保持最新。 當文檔隨著底層代碼和對話的變化而自動更新時，關於「文檔過時」的反對意見就不攻自破了。工程師願意審閱並完善他們相信基本準確的文檔。但他們不願意撰寫明知在一個月內就會出錯的文檔。

通過格式明確受眾。 不要要求工程師為不確定的受眾撰寫，而是提供結構化的格式：用於架構決策的決策日誌、用於新員工的入職文檔、用於系統文檔的工程 wiki。每種格式都暗示了其受眾，這使得撰寫（或審閱）任務變得有邊界，而不是開放式的。

審閱模式

最可持續的文檔模式是將工程師視為審閱者而非作者。系統從可用來源（代碼活動、對話、會議）生成初始文檔。工程師進行審閱、修正和補充。審閱是一項 10 分鐘的任務，而不是 2 小時的寫作課，上下文切換極小，而且工程師的貢獻是對已有內容進行質量保證，而不是從零開始創建。

這種模式尊重工程師的時間，解決了他們的反對意見，並能產生保持最新的文檔。它也往往比手動撰寫產生更好的文檔，因為生成的文檔更全面（捕捉發生的所有事情，而不是工程師記住要寫下來的事情）且一致（遵循標準格式，而不是因作者而異）。

常見問題

那些真正喜歡寫文檔的工程師怎麼辦？ 他們存在且很有價值。在審閱模式中，他們成為豐富和改善生成文檔的人，添加自動化系統無法產生的細微差別、上下文和敘事。他們的技能更適合用於豐富內容，而不是系統處理的基礎寫作。

工程師會信任 AI 生成的文檔嗎？ 比你想像的更容易，因為文檔是從工程師認可的來源生成的：他們自己的 PR、他們自己的 Slack 線索、他們自己的會議討論。文檔引用了這些來源，因此工程師可以通過檢查原文來驗證任何說法。信任建立在透明之上，而有引用支持的生成提供了這一點。

我們如何處理機密或敏感信息？ 系統應該為其捕獲的內容設置可配置的邊界。可以排除某些 Slack 頻道、某些代碼庫或某些會議類別。工程師控制系統看到的內容，這意味著敏感信息不會進入生成的文檔。

延伸閱讀：撰寫工程文檔的成本、文檔悖論、自撰寫文檔詳解。相關頁面：自撰寫文檔、適用於工程團隊。