1. Tutorial：新手的烹飪教室
用途與特點
- Learning by doing：透過親手操作而非大量閱讀理論，快速上手。
- Getting started：帶新手從零開始，像教孩子如何從洗手、備料，到完成一道料理。
- Inspiring confidence：每個小步驟都有成就感，讓人有繼續下去的動力。
- Repeatability：保證任何人、在任何環境都能跟著做出相同成果。
- Immediate sense of achievement：步驟設計清楚，不會半途而廢。
- Concreteness, not abstraction：專注於實際操作，不在此處大談概念理論。
- Minimum necessary explanation：只解釋「現在就用得上」的東西，避免塞入過多背景知識。
- No distractions：不提供可選方案或進階討論，確保新手不被過度資訊淹沒。
類似廚房場景
這就像帶孩子第一次下廚，手把手示範：先洗手、準備食材、確認溫度……一步步走，確保孩子可以立即完成一道料理，獲得成就感。
2. How-to Guide：精準對焦的食譜
用途與特點
- A series of steps：針對某個「明確問題」提供可重複的操作步驟。
- Focus on the goal：明確告訴讀者「我們要做出什麼成果」。
- Addressing a specific question：像「如何設定 LDAP 認證」或「如何建立網頁表單」，有明確的問題即有明確解答。
- No unnecessary explanation：只談必須知道的步驟或設定，不在此贅述理論或背景。
- A little flexibility：步驟可依情況做些許調整，讓讀者可在類似需求下舉一反三。
- Practical usability：實用第一，確保讀者能快速運用在真實情境。
- Good naming：清楚命名標題與內容，讓讀者一眼就知道能解決什麼問題。
類似廚房場景
這部分就像一本「料理食譜」，直截了當告訴你「如何做出一道番茄義大利麵」，從準備哪些食材、下鍋順序，到火候掌握，步驟明確、結果可預期。
3. Reference：廚房的詳細資料櫃
用途與特點
- Structure：結構應與程式碼一一對應，讓讀者在查閱或維護時能快速定位。
- Consistency：風格、用語、命名等要前後一致，如同字典或百科條目。
- Description：提供清晰、完整的屬性、方法、類別、API 等技術細節。
- Accuracy：必須與程式碼保持同步，避免資訊過時或錯誤。
類似廚房場景
就像廚房裡的「工具與食材大辭典」：
- 介紹每種食材（程式碼中的類別/函式）的產地、特色與使用方式。
- 讓有需要的人能快速查到「薑」或「黑胡椒粉」的功能、相容性及注意事項。
這裡不提供教學或解題步驟，只做「精準描述」之用。
4. Explanation（Discussion）：料理背後的深度對談
「Explanation, or discussions, clarify and illuminate a particular topic. They broaden the documentation’s coverage of a topic.」
用途與特點
- Giving context：解釋軟體/功能背後的脈絡，或在更寬廣的背景下談論「這是什麼、為何存在」。
- Explaining why：討論設計決策的緣由、歷史沿革、技術約束等。
- Multiple examples, alternative approaches：比較各種可能路徑、觀點，甚至包含錯誤示範。
- Making connections：連結不同概念與領域，提升讀者的理解層次。
- No instruction or technical description：不提供操作步驟，也非技術參考，重點在開闊讀者視野。
類似廚房場景
想像一本專門探討「飲食史、科學與文化」的書，它不會教你如何操作鍋碗瓢盆、也不是食譜或材料大辭典，而是從更高層次剖析「我們為什麼這樣烹調」，或者「其他國家有怎樣的料理方式」，讓人對整個飲食文化有更深層的理解。
寫好 Explanation 的關鍵
- 提供背景：例如，你可以討論 Django 的表單處理方式是如何演化而來、為何做這些設計取捨。
- 評估替代方案：像在部署 Django 時，可能考慮多種 Web 伺服器選項，這裡就能討論它們的利弊。
- 不做操作教學：不要讓讀者在這裡學怎麼操作，那應該放在 Tutorial 或 How-to Guide。
- 命題彈性：不像 How-to 有明確問題，Explanation 取決於「你想討論什麼範圍」，比較自由但也更難著手。
為什麼要分清這四類？
正如我們一開始所說：「文件不是一種，而是多個功能組合」。若你把教學操作、問題解答、詳細參考和深度討論全都擠在同一地方，讀者會像走進一個廚房 — — 醬料、刀具和書本全亂放在同一個檯面。
- 降低學習門檻：新手想先看教學，老手想查 API，大師想看背景或設計理念，各取所需。
- 便於維護：開發者只要在對應的區塊更新內容，不會像拔一根線卻影響整個系統。
- 提升可讀性：清楚的結構能幫讀者快速找到答案，也不會被過量資訊轟炸。
結語
「根本沒有一種叫做『文件』的東西！」 這句話的核心意思是：文件並非單一類型，而是由 Tutorial（教學）、How-to（解題）、Reference（參考） 和 Explanation（討論） 四種功能組合而成。每一部分都有自己獨立的焦點與責任，互相配合才能形成一份真正「好用」的文件。
就像一間分工明確的廚房：
- 教學工作站（Tutorial） 指導新人從零開始；
- 食譜工作站（How-to Guide） 精準解決特定需求；
- 資料櫃工作站（Reference） 詳細記載每種工具食材；
- 深度對談工作站（Explanation/Discussion） 從更高層次審視與討論。
如果你想讓開發團隊或使用者對你的專案「一試成主顧」，不妨試著替文件「分流」：想學操作就去看教學，想解難題就去看 How-to，想查技術細節就去 Reference，想理解前因後果就去 Explanation。相信只要善用這四大類型，你的文件也能像一桌精心設計的饗宴，讓所有人都吃得滿意、看得舒心。
