diataxis documentation

Hugo 文檔的問題眾所皆知，甚至爛到上 Hacker News 討論，比如說文檔的這張擷圖，你能找到怎麼安裝 Hugo 嗎？

沒錯，Hugo 文檔使用卡片設計而且還是字母排序，所以安裝教學甚至不在前九個是在第十二個，關於文檔有多爛可以看我在 discourse.hugo.io 發的 thread，可惜 maintainer 完全沒興趣^[1]。

這篇文章的目的有兩個，首先是簡述 Diátaxis 架構，再來是除了架構本身，UI 應該要如何設計才能達成配合 Diátaxis 達到最好效果。

Diátaxis 架構

這裡不會仔細介紹組織方式，因為這樣讀者自己去看文檔就好了，原文沒多長，我重寫一次也沒有意義，最重要的是任何節錄式的說明反而容易忽略更多重要內容並且誤以為自己已經懂了。

Diátaxis 按照四個順序寫文檔：

1. 教學 Tutorial
2. 操作指南 How to
3. 參考 Reference
4. 解釋 Explanation

官網除了順序以外還對這些要點區分了四個象限，不過我覺得象限不是特別重要，重點是編排。首先 Tutorial 必須要是教學是超簡單，讓人馬上有成就感且馬上能運行的手把手教學，How to 則涵蓋所有日常常見用法，Reference 的內容應該以字母排序，列表式寫出所有可用方法。為什麼我沒有說到 Explanation 呢？因為有些情況如果不理解原理看了細節也不知其所以然，導致不敢用或者亂用，因此我認為 Explanation 應該放在 Reference 之前。

適合 Diátaxis 的網站介面

截至 2025 的現在三行式佈局加上 top navigation 就是最好的設計沒有之一，最簡單的判斷原因是大家都用他。

曾經我也想過為什麼全部文檔都用三行式，從臉書贊助的 Docusaurus 是這樣設計，然後 React 這些臉書開發的架構當然也用 Docusaurus 寫文檔，然後 Vitepress 也是，MkDocs 是三行佈局，從開源變成閉源的 GitBook 也是三行佈局，這些全世界最受歡迎的工具背景框架橫跨 React/Vue/Python 全部採用相同的佈局方式，一直到沒用架站工具的 MDN 文檔、微軟文檔、VsCode、Github 文檔也無一例外，當時的我覺得真無聊所有人都用一樣的設計，然而換個角度想原因就很簡單清晰，三行式佈局就是最適合文檔的網站介面。

這有幾個原因：

1. top navigation 可以用作完全不同的 section 分區，新手不需要去老手區找東西，老手也永遠不用浪費時間過濾新手區的內容，最常見的分法就是 Docusaurus 和 Vitepress 將其分成 教學+操作指南 以及 參考 兩個大分類，兩區的編排方式完全不同，目標讀者也完全不同
2. 讀者永遠知道自己讀到文檔的哪個部分
3. 基於二，完美契合 Diátaxis，因為這種介面引導讀者閱讀，只須從上往下讀就能保證理解和使用
4. 基於三，這也隱性的引導讀者該如何閱讀，不需要到處寫 what's next
5. 如果內容很複雜，你甚至可以把 top navigation 切的更碎，像是 shiki 切分成 教學+操作指南 整合其他工具 參考 部落格（對應 Diátaxis 的解釋） 多個區域，一目了然，也知道根據自己的需求哪些區域永遠不需要點進去

由此可知三行佈局就是最適合 Diátaxis 的網站介面，就算不按照 Diátaxis 使用其他框架，只要文檔需要這些優點，那也應該使用三行式佈局^[2]。

值得深入的細節

外國有很多 technical writing 相關的文章，台灣沒有，我想主因是薪水少的可憐，然而一個好的文檔可以大幅提升工作效率，不相信的話去看 Hugo 文檔就知道他降低了多少工作效率了。

簡單列出幾篇我放在書籤的文章：

1. Top 10 tips for Microsoft style and voice

   1. Use bigger ideas, fewer words
   2. Project friendliness
   3. Get to the point fast
   4. Be brief
   5. Don't be spacey
   6. ...

2. English Grammar Rules for Technical Documents: 20 Dos and Don’ts

3. DigitalOcean's Technical Writing Guidelines

4. The Draft.dev Technical Blogging Style Guide

   文章的引言應該要包含：

   • What’s the pain point I’m addressing here? How do I hook my readers?
   • What’s the solution to this problem?
   • What am I going to do in this article?
   • Support Claims With Evidence

5. SUSE Documentation Style Guide (AsciiDoc) / Writing for the Web

6. 【LangChain 速递】LangChain 文档重构解读

7. Rethinking Our Documentation

小結

框架、內容、用語、介面缺一不可，不過 Hugo 全都缺就是了。