四種文檔的種類，以及為什麼需要了解它們

前言

好的文檔應更容易的被撰寫，更簡單去維護

什麼是文檔(documentation)？狹義來說多指與程式有關的說明性文本，但其實生活中大大小小的事都能是文檔。常見到的技術教學是一種文檔，煮飯菜時的食譜也是一種文檔，基本上就是指技術性的攻略、參考文件，掌握文檔的撰寫方式，就是掌握如何更好的將知識散布，被人所理解使用。

對於作者來說……

最大的頭痛，來自於文檔需要維護，學習這樣的架構可以幫助他們更清晰的了結如何撰寫文檔，以及應該如何分類，來去幫助自己與讀者。

對於讀者來說……

更清晰的了解在不同的學習階段獲取能夠最大效益提升自己知識的方式。

好的文檔，四個種類

我認為好的文檔就是「留意於目前讀者想了解的知識」放大重點並去除其他的雜訊，詳細來說會有哪幾種目的的讀者呢？

• 學習為主軸 - 想學習某個領域
• 目標為主軸 - 想解決某個問題
• 資訊為主軸 - 想獲取某些資訊
• 理解為主軸 - 想了解某些資訊

觀察讀者的需求，給出對應的解答，依循以上 4 點的需求，總結出 4 點可以著重的點，將文檔分類為幾個種類 ——

• 教學 - 引導、成就感為重
• 操作 - 目的達成為重
• 參考 - 資訊清晰完整為重
• 解釋 - 理解思考脈絡為重

教學 Tutorial

教學文檔應是以引導與成就感為重

教學，讓讀者能夠快速的開始，了解藉由教學能達成一些具有成就感、有意義的事情，舉例來說：教導一個人如何烘焙。

最終，教會那個人什麼並不重要，重要的是這份教學是讓人受鼓舞的、感興趣的、想再去嘗試的、是良好的體驗，就是好的教學。

教學的過程是有趣的、忽略技術細節的，這類的文章必須避免解釋與討論任何抽象或過於深奧的概念，通常針對特定的領域探討，從做中學，具備齊發性質。教學是所有文檔性質中最困難的，最好的方式，是作為導師盡量與學生(讀者)互動。個人認為，在這個階段 WHY 會大於 HOW，也就是為「為什麼要學習 X 」會比「要怎麼學習 X 」還要重要得多，啟動學生的學習動機。

• 從做中學 (創造知識的墊腳石)
• 從簡單的事情開始 (並不一定要是最好的範例，但要清晰簡白到能讓初心者入門，而不是幫助他們到達終點)
• 能立即看見成果 (確保每一個動作是微小但可見成效的)
• 提供最低限度完成教學的解釋 (其餘的都會增加分心與困惑)

操作 How-To Guide

操作文檔應以達成某種目的為重

操作，展示解決特定問題的流程做法，了解藉由閱讀就能解決某個問題，或達成某種目的，舉例來說：杯子蛋糕的食譜。 如果說教學是給初心者的入門指南，那麼操作就是給具有一定知識背景的人所提問的解答。就好比有一定基礎的甜點師傅，可以依循食譜去製作杯子蛋糕。

過程應是以達成某個特定的目的為主，以目的為導向，這類的文章同樣必須避免解釋與討論任何抽象的概念，唯一的重點，就是思考如何盡快簡白的達成某個期望的目標。

• 命名很重要 (文檔的標題應該清晰的表達單一明瞭的目標)
• 提供一系列的明確步驟 (就像教學一樣)
• 著重於結果 (必須著重於達成某個特定的目標)
• 不要解釋概念 (如果概念很重要，附註於文檔之外)
• 允許靈活性 (允許不同的方式去達成同個目標，讓學生有想像、自我學習的空間)

參考 Refence

參考文檔應以理解思考脈絡為重

參考，描述事情的功能性、互動方式，讓讀者了解到藉由閱讀就能從中獲取想要的資訊，舉例來說：維基百科。 過程應以描述細節資訊為導向，因此擁有高度的一致性、語調和文法精確的描述是重要的，嚴肅且直擊重點。

• 格式、語調、保持一致 (就像字典一樣)
• 清晰的描述 (解釋、討論、操作、猜測、意見都只會分散注意力)

解釋 Explanation

解釋文檔應以資訊清晰完整為重

解釋，闡明、分析、明朗化特定的主題，擴張對於某個主題的範圍，從不同的角度。舉例來說：一本討論烹飪史的書。使用多種面向去面對一個問題，退後一步去更廣闊的了解事情的全貌。解釋對於某個主題的看法，供讀者通常在閒暇之餘去擴充某的主題的知識。

過程應充分給予前後文(Context)並省去步驟與技術細節，並採用多重的範例與假設替代的做法。

• 提供前後文 (解釋事情的背景條件和歷史，如：設計抉擇、技術限制、歷史因素)
• 討論不同的面相和選擇 (多種的觀點與分析解釋)
• 不討論技術細節與步驟 (這類內容在其他類型的文檔中撰寫吧)

總結

本篇文章擷取 Daniele Procida🔗 在 Write the Docs EU🔗 和 PyCon Australia🔗 上發表的演說所總結的觀點筆記。雖然這樣的概念主要還是面向對於程式開發者撰寫文檔的方式總結，不過我認為同樣可以將這樣的概念仍適用在各類文檔上幫上用場。

資料來源

• The four kinds of documentation, and why you need to understand what they are🔗
• The documentation system🔗