TL;DR
文件無法發揮效果，通常源自於「目標讀者」和「實際讀者」兩者之間出現落差。
Divio 的 Documentation System 框架將文件分為四種類型，幫助作者根據不同讀者的需求撰寫合適的文件。
藉由分類標籤，讀者能更快找到對應的文件，提升知識傳播效果，最終讓文件成為實際有效的溝通工具。
文件無法發揮效果，為什麼？
在組織中，文件常常是許多人的痛，當自己是寫文件的人時，常常會覺得：
X! 使用者都不來看我的文件，是怎樣？
但當自己在看別人寫的文件時，又常會有種 :
X! 這傢伙到底在寫什麼？
我在今年 Hello World Dev Conference 的分享中提到 :
對於組織來說，問題不是「沒有文件」，而是「文件沒有發揮效果」。
為什麼會這樣子？ 對於文件的「作者」來說，你可能常常會想 :
這些內容，我都有寫在文件上啊！但使用者不看，我有什麼辦法？
讓我們試著做個「換位思考」的練習 : 假設今天你剛加入了一個新團隊，你希望快速了解團隊內的 CI/CD Pipeline 要如何使用，於是你在組織的知識庫中下了關鍵字 : CI/CD Pipeline，接著你得到…
(借用今年 HelloWold Dev Conference 2024 的簡報)
身為新人，你該如何在這些結果中，快速找出適合你的文件？ 是不是很難？
對讀者而言，痛點在於：很難從標題了解這份文件需不需要先備知識？ 目的是什麼？
為了要讓「文件」發揮效果，我們可以怎麼做呢？
我認為 Documentation System 是個很棒的框架，能夠有效提升組織內文件的溝通效率。
About Documentation System
在組織負責設計、維護 CI/CD 流程時，免不了要將「新流程」推廣給組織內的其他工程師，因此常會需要撰寫「文件」來降低溝通的成本。
但在初期，真的覺得很挫折，寫作時很難寫出切中目標受眾、內容不發散的文件，有時候好不容易完成，卻沒辦法發揮效果。
後來在無意間留意到 Divio 公司推廣的 Documentation System，實際上導入團隊後，對於整體的文件品質，有很顯著的提升。
什麼是 Documentation System ?
這個框架的核心精神是：把文件劃分為四種類型，每一種類型的受眾、重視的面向都不盡相同，將重點聚焦在對的人、對的事上，可以讓文件的內容更切中讀者的需求。
這四類分別是 :
- Tutorial
- How-to Guide
- Reference
- Explanation
為了讓各位讀者了解四種類型文件的差異，讓我們來個生活化的例子：
今天你養了一隻可愛的寵物豬，但它很不受控，常常隨地便溺，讓你很頭痛，但它太可愛了！我們希望它能變得更好！
在這樣的情境下，如果有四種類型的文件能幫助我們，會有什麼區別呢？
我希望各位在閱讀接下來的內容時，可以特別關注兩個面向：
- 該類型的文件對於目標讀者的技能要求是什麼？
- 該類型的文件是希望「提升讀者的能力」還是「解決讀者的問題」？
Tutorial
Tutorial 是專門寫給「新手」看的文件，目的是希望讀者看完文件後，能夠在實際體驗的過程中，感受到「樂趣」、「成就感」等正向體驗，從而繼續這趟旅程 (使用你的產品)。
由於讀者是毫無經驗的小白，所以 Tutorial 通常會假定讀者沒有「思考和解決問題的能力」，這意味著在 Tutorial 中，所有行為都必須要「具體」且「明確」，一但讀者遭遇到 Tutorial 上沒有撰寫的情境，大部分的讀者可能會選擇「放棄」。
在小豬情境中，Tutorial 可能會長得像是…
[Tutorial] - 如何教你的豬使用馬桶 (從零開始)
1. 將馬桶放在豬活動範圍內，讓它習慣馬桶的存在。
2. 當豬準備如廁時，輕輕引導它靠近馬桶並給予獎勵。
3. 當豬在馬桶上如廁成功後，給予食物獎勵。
持續這樣重複直到豬完全學會使用馬桶。
How-to Guide
How-to Guide 可以說是大部分工程師最擅長寫的文件類型！
相較於 Tutorial 是希望「將讀者轉換為使用者」，How-to Guide 的目的則是要「解決一個特定的問題」，所以這種類型的文件有一個特色：標題明確、直接陳述該文件要解決什麼問題。
在目標讀者的設定，這類型文件會假定讀者已經具備基本的先備知識，專注在「精準」且「有效」的解決讀者的問題。
不需要在文件中談論方法論、概念說明，只需要提供具體的策略，幫助讀者解決問題，就是好的 How-to Guide。
在小豬情境中，How-to Guide 會長的像是…
[How-to Guide] - 如何讓你的豬喜歡馬桶而非簡單的傢俱?
豬是好奇心強的動物，牠們可能會對家裡的家具產生興趣，特別是在如廁的問題上。然而，你可以透過一些簡單的步驟，幫助你的豬更喜歡馬桶而不是隨意選擇家具。
1. 選擇一個合適的馬桶位置
確保馬桶擺放的位置方便豬接觸，且處於豬經常活動的區域。選擇一個安靜、舒適的角落，讓豬覺得這裡是牠的「專屬空間」。
2. 逐步引導豬認識馬桶
每當你發現豬準備如廁時，輕輕地將牠引導至馬桶旁。可以輕柔地抚摸豬，並用溫和的語氣給予鼓勵，讓豬慢慢適應並認為馬桶是一個安全的地方。
3. 使用獎勵加強行為
當豬成功在馬桶上如廁後，立即給予食物獎勵，像是牠最喜歡的小水果或蔬菜，這樣可以強化牠的行為，並讓牠聯想到在馬桶上如廁有正向的結果。
4. 減少家具的誘惑
同時，盡量避免讓豬靠近那些容易被牠誤以為是如廁點的家具。例如，可以在家具附近放置不喜歡的氣味，或者在豬學會使用馬桶前，用物理障礙阻擋牠靠近這些區域。
Reference
Reference 類型的文件，不像 Tutorial 預先設定讀者的類型，也不像 How-to Guide，整份文件的目的就是要帶領讀者解決特定問題。
對於 Reference 來說，最重要的任務就是 : 提供資訊，而且是以「簡樸」的形式來提供資訊，也就是在提供資訊時，不提供過多的說明。
就像百科全書，雖然提供了豐富的資訊，但不會預設讀者是誰、需要怎麼理解這些資訊。
如 OpenAPI , SwaggerUI 等 API Documentation 工具，都可以算是 Reference 的範疇。
回到我們的小豬情境，Reference 可能會長得像是…
[Reference] - 寵物豬馬桶訓練的技術指南
- 豬的如廁頻率：平均每4小時一次。
- 推薦獎勵物：小顆的水果或蔬菜塊。
- 訓練時間：通常需2-4週。
這些數據可以幫助你根據豬的行為調整訓練計畫。
Explanation
Explanation 文件的目的是闡述、說明一個概念，增加讀者對於特定主題的深度與廣度。
相較於 Tutorial 和 How-to Guide，Explanation 的範圍通常由作者自行決定，主題的設定較為隨意。
對於讀者來說，閱讀 Explanation 是輕鬆的，透過文件來了解不同面向的觀點，從而增加自身的新知識。
對於小豬飼主來說，一份 Explanation 可能會是…
[Explanation] - 為什麼訓練豬使用馬桶是個好主意？
訓練你的豬使用馬桶不僅可以保持環境清潔，還能增進你與豬之間的互動。然而，這其中包含了很多值得討論的概念和理由。首先，豬是高度智慧的動物，牠們能夠理解並習慣複雜的行為模式。透過如廁訓練，你不僅在強化豬的認知能力，還能讓牠感受到規律生活的益處。
另一方面，從衛生角度來看，教豬使用馬桶能夠減少家居中的異味和混亂。與簡單的如廁墊相比，馬桶是一個更具長期效益的解決方案。
最後，這也帶來了更多思考：如何選擇適合豬的訓練方法？什麼樣的獎勵機制最有效？豬對行為習慣的形成時間會因年齡和個性不同而有所差異，這是需要根據情況調整的。這些都是需要深入理解和討論的概念，讓整個訓練過程更為成功。
Documentation System 怎麼派上用場？
快速的了解 Documentation System 的框架和原則後，現在讓我們回到剛剛「加入新團隊」的情境，如果我們可以在文件上看出每一份文件的種類 :
加上對應的分類後，讀者們可以根據自身的狀態，進行對應的行為，舉例來說：
- 對於新加入團隊的新人，應該優先 「查看」
[Tutorial]標籤的文件。 - 對於資深的員工，則應該優先 「排除」
[Tutorial]標籤的文件。
Documentation System 讓讀者除了「文件標題」外，還能從文件的類型得到額外的資訊：這份文件「對於目標讀者的熟練度要求」以及「目的」，這些資訊能夠幫助讀者快速找到適合的文件，增加知識傳播的效果。
Conclusion
我的主管曾說過 :
只有自己看得懂的叫做「筆記」，別人看得懂的才叫做「文件」
然而，一份文件能不能發揮效果，除了作者的寫作功力外，還有一個關鍵因素：作者設定的「目標讀者」與「實際讀者」是否吻合？
當兩者背景差異過大時，寫作功力再怎麼好，都會落入「讀者無法理解」的下場，從而導致文件無法正確發揮效果。
Documentation System 藉由分類，試圖讓「作者」和「讀者」有明確的標準去對齊兩者的認知，協助讀者找到「最貼近自己程度和目的」的文件。
在實際導入 Documentation System 的思維後，團隊內的文件可以更精準的設定目標讀者，也能在知識庫中更好的分類，對於組織的知識傳遞，我認為起到了很正向的效果。
在這邊也分享部門大神 Kellen 哥的 Medium，以 Documentation System 為基礎，寫了一系列的雲端文章，從不同面向、角度去切入，各位讀者有興趣的話歡迎造訪，實際感受不同類型的文件帶來的差異。
如果你對於具體的寫作指引有興趣，歡迎前往下集 : 我也想好好寫文件 - Documentation System 的具體寫作指引
感謝你的閱讀，我們下次見！