Diátaxis: A Systematic Framework for Technical Documentation

Diátaxis 是一種系統化的技術文件編寫方法，根據使用者的特定需求來組織內容。透過將文件分為四個不同的象限——教學 (tutorials)、操作指南 (how-to guides)、技術參考 (technical reference) 和說明 (explanation)——它解決了關於寫什麼 (內容)、如何寫 (風格) 以及如何組織 (架構) 的常見問題。

The Four Quadrants of Diátaxis

Diátaxis 建議了四種對應的文件形式，每種形式都旨在滿足不同的使用者需求。該框架確保內容的「說話語氣」和結構能與使用者當下的目標相匹配。

Tutorials (Learning-oriented)

教學 (Tutorials) 是為初學者設計的，旨在讓他們達成一個微小且成功的成果。它們以教學為導向，引導使用者透過一系列步驟來開始使用一個系統。

How-to Guides (Task-oriented)

操作指南 (How-to Guides) 是為已有特定目標的使用者設計的。與教學不同，它們不進行教學；它們為已經具備必要先備知識的使用者提供完成具體任務的直接路徑。

Technical Reference (Information-oriented)

技術參考 (Technical Reference) 提供關於系統機制運作的描述性資訊。這類內容專注於準確性和一致性，通常利用圖表、項目符號和結構化列表來描述 API、類別 (classes) 或配置選項。

Explanation (Understanding-oriented)

說明 (Explanation) 提供系統的理論背景和概念性理解。它是論述性的，專注於「為什麼」事物會以這種方式運作，而不是「如何」執行特定動作。

Implementation and Practical Application

Diátaxis 是一種輕量級且與實作方式無關的框架，這意味著它不會對文件的託管或編寫方式施加特定的軟體限制。它作為資訊架構的「北極星」，幫助維護者決定新內容應該放在哪裡。

Industry Adoption

幾家主要組織已將 Diátaxis 整合到他們的文件工作流程中：

• Cloudflare: 使用該框架作為重新設計開發者文件時的資訊架構指南。
• Gatsby: 重新組織開源文件，透過四個象限來優先考慮使用者目標。
• Vonage: 為使用者和貢獻者建立了高品質的內部文件。

Integration with Other Tools

社群中的實踐者建議，當 Diátaxis 與其他結構化文件工具搭配使用時效果最佳。一位使用者指出，「Diataxis + ADRs (Architecture Decision Records) + C4 (C4 model for visualizing software architecture)」的組合可以建立一個全面的文件生態系統。

Critical Insights and Community Feedback

雖然該框架因能為作者提供清晰度和一致的「語氣」而廣受讚譽，但它也面臨來自開發者社群的批評和實際挑戰。

Navigation and Accessibility

有些使用者警告，不要為了遵循框架而犧牲了可用性。一個常見的批評是，嚴格遵守四個象限可能會導致「2-click docs」，即必要的 API 參考文件被隱藏在「Reference」分頁下，而不是透過頂層連結直接存取。

Maintenance and Drift

在四種不同的類型之間維護文件可能會導致「內容漂移 (content drift)」，即隨著軟體演進，教學或參考文件變得過時。社群成員建議實施驗證時間戳記或從版本化的代碼中自動生成文件，以減輕這種風險。

Comparison to Other Models

一些開發者建議了替代或互補的模型，例如「Fabrizio's seven actions」，其專注於使用者的心理狀態（評估、理解、探索、練習、記憶、發展和疑難排解），而非結構化分類。

LLM Integration

最近的趨勢顯示，Diátaxis 對於 AI 輔助文件編寫非常有效。使用者回報，要求 LLM 「do diataxis」會產生更高品質的第一版文件，因為它為模型提供了清晰的結構化約束。