TL;DR
撰寫文件時，常常會遇到目標讀者和寫作方向失焦的問題。Documentation System 提供了有效的框架，幫助作者釐清目的與目標，避免資訊過多或混亂。
不同類型的文件，如 Tutorial、How-to Guide、Reference 和 Explanation，各有不同的寫作重點。
寫文件為什麼困難？
在前一篇文章：拜託你看看文件好不好?? - 淺談 Documentation System 中，談到對於「文件讀者」來說，很難從「標題」獲得足夠的資訊，判斷這份文件是不是自己需要的。當作者所設定的目標讀者與讀者出現落差時，文件容易失去應有的效果。
對於文件寫作者來說，如何在寫作過程中，維持既有的目標讀者，不偏離原先設定的主軸，其實是很困難的。
以我為例，剛開始寫文件時，可能是希望「讓讀者了解該如何解決問題」，但是在寫作過程中，開始陷入迷惘：
- 如果我從基本概念開始寫，那大概要寫兩萬個字才有辦法鋪陳完畢，那太花時間了！不行！
- 如果我直接切入問題核心，那讀者會看得懂嗎？ 不行！我好像應該要加點說明！
在寫作的過程中，這兩種聲音會互相拉扯，導致最後寫出的文件變得四不像，新手看不太懂，又無法真正解決問題。
我們需要一點寫作框架！
在今年的 Hello World Dev Conference 中，我分享了自己非常喜歡的一本書：由劉奕酉寫的高產出的本事: 用8種表達框架X4張圖X15分鐘, 文章、簡報, 圖解一次到位, 讓輸出成為你的優勢，書中提到了一個概念 :
框架 = 讓人輕鬆理解的概念。
我認為 Documentation System 就是一種給工程師的「寫作框架」，設定好自己的文件類型和目標客群後，能夠參考具體的指南來寫作，在這些指引的協助下，能夠避免越寫越混亂的窘境。
接下來我想針對四種不同類型的文件，整理出自己的筆記，如果對於原版內容有興趣的讀者，歡迎至 Divio 官網查閱 Documentation System 的相關內容。
(如果你還不知道什麼是 Documentation System，可以先看看前一篇介紹文章: 拜託你看看文件好不好?? - 淺談 Documentation System)
1. Tutorial 的寫作原則
Tutorial 的目的是幫助讀者開始旅程
Tutorial 的目的是協助讀者能夠「踏上旅程」，而不是「到達正確的目的地」。
當讀者可以在閱讀、實作的過程中取得成就感，才有機會從「讀者」轉換為「使用者」，為了達成這個目的，需要用最快的速度讓讀者開始嘗試，就算這個初始配置是「不標準」甚至「不合理」的，也沒有關係。
舉例來說，如果讀者需要先花費 30 分鐘預先註冊、認證，才能開始按照 Tutorial 操作，雖然流程上這是正確的，但讀者可能根本無法完成這份 Tutorial 就直接被嚇跑了。
Tutorial 先別談概念
在撰寫 Tutorial 時，應該要努力克制「說明」的慾望，例如在 Tutorial 中向新手分享「這東西有多酷！為什麼它可以這麼酷！」，如果在一份 Tutorial 中談論抽象的概念，例如：系統的精妙之處、可以改善什麼問題…，這將會是一份糟糕的 Tutorial。
在學習時，應該要先了解具體的功能、事物，有了基本認知後，再嘗試理解抽象的概念。
所以在 Tutorial 中，要刻意將非必要的「概念說明」、「延伸討論」抽離，這些內容並非不重要，而是不需要出現在 Tutorial 中，我們可以在稍後的 Explanation 中達到同等效果。
Tutorial 只需要提供具體且明確的任務目標，並透過一系列的步驟來協助讀者完成。
Tutorial 的作者扮演著「去蕪存菁」的角色，過多的資訊量有礙新手成長，該如何從新手的角度出發，進行「資訊的取捨」，讓讀者能攝取關鍵的資訊，從而獲得最好的吸收效率，這是 Tutorial 應該要關注的重點。
讀者只需要掌握必要的資訊，讓他繼續進行這趟旅程，後續會有不同類型的文件，幫助讀者掌握這些資訊，Tutorial 的目的只有 : 讓讀者繼續這趟旅程。
Tutorial 要有具體的步驟和結果
由於 Tutorial 的目標讀者為「新手」，也就是對於文件探討的內容一無所知，在撰寫 Tutorial 時，有一個非常重要的重點：
務必要確保「要求使用者做的事情」會成功
要達到這個目標，其實可以拆解成兩個任務：
- 執行的結果要能被具體觀測到。
- 執行過程和文件的記載必須完全一致。
由於新手對於工具、系統、流程都毫無概念，撰寫 Tutorial 時，最好能讓每一個步驟都有「具體的結果」，確保每一個步驟的結果清晰可見，且步驟與步驟間具有顯而易見的相依關係，有助於讀者確保自己正在正確的路徑上。
當執行結果發生「異常」，或許是發生錯誤、或是結果與 Tutorial 上不相同，新手是不會有能力和興趣進行排障的，大部分人的選擇會是…「直接放棄」，這時候 Tutorial 反而產生反效果。
2. How-to Guide 的寫作原則
How-to Guide 的存在是為了解決特定的問題
How-to Guide 和 Tutorial 最大的差異 :
- Tutorial 是由作者決定讀者需要了解什麼。
- How-to Guide 的讀者已經知道自己要去哪裡，只是不知道該怎麼去。
在命名時，最好能在標題就清楚傳達這則筆記的核心概念，也就是：「要解決什麼問題？」，讓讀者可以快速掌握這份文件的使用場景。
How-to Guide 專注在一系列的步驟
How-to Guide 和 Tutorial 相同，都會包含數個具體的步驟，關鍵在於解決問題而非「提供說明」，但最大的差異在於：
How-to Guide 的讀者已經具備基本知識，也有足夠的使用經驗，因此 How-to Guide 不需要從零開始，只需要一個「具體」且「明確」的起始點。
不需要像 Tutorial 一樣帶著讀者站上起點，只需要提供合理的描述，讓讀者自行前往起始點。
接著透過一系列的步驟，指引讀者「抵達目標」（通常目標就是問題被解決）。
確保 How-to Guide 有足夠的泛用性
在設計 How-to Guide 時，盡可能保留一些彈性和泛用性，更準確的說：不要侷限在使用「單一種方法」解決「單一種情境」，而是讓讀者在閱讀完 How-to Guide 後，能夠舉一反三，使用「類似的方法」處理「類似的問題」。
當 How-to Guide 具有泛用性時，整份文件可以發揮更大的影響力，反過來說，如果在未來只能處理完全相同的情境和問題，那價值就會下降許多。
3. Reference 寫作原則
Reference 盡可能與 Codebase 維持相同結構
在先前的文章(拜託你看看文件好不好?? - 淺談 Documentation System)中有提到: Reference 的重點是提供資訊，因此在寫作上，需要特別考慮「如何讓讀者可以快速取得所需的資訊」。
撰寫 Reference 時，最好能讓文件和 Codebase 有相同的結構，目的是讓讀者在使用 Codebase 時，能一眼就對照出所需資訊放在文件的哪個位置，從而降低讀者的認知負荷。
Reference 的簡潔性與一致性
當 Reference 中加入了過多的「說明」、「討論」、「類比」，都會讓這份 Reference 變得難以使用，且後續不易維護。
在適當的時候，可以透過具體的範例來說明「如何操作」，例如許多 API 常用的 Swagger UI 就會在提供資訊的同時，包含必要的「範例」，讓使用者了解如和使用。
撰寫 Reference 時，可以想像在維護字典或是百科全書，確保整份文件具有相同的語調、格式、結構。
4. Explanation 寫作原則
Explanation 需要提供 Context
Explanation 是相對寬鬆和自由的文件類型，主要的目的就是補強其他類型文件的不足。
可以將 Explanation 拿來作為「設計理念」、「歷史共業」的說明，也有人會拿這類型的文件來探討數個「可行方案」的差異，或是針對完全相反的意見進行深入的討論。 (類似於 Architecture Decision Records)
唯一要注意的一點，由於 Explanation 通常是溝通概念，需要先替讀者建立好 Context 和背景知識，只有讀者和作者都處在相同的 Context 下，兩者間才能透過文件進行有效的溝通或知識傳遞。
總結
過去當我在寫作文件時，常常會在過程中迷失「目標讀者」的樣貌，導致寫作內容開始失焦、資訊量過度膨脹，導致最後的文件過於混亂。
Documentation System 像是一個定位羅盤，在寫作文件前，先思考這份文件想要達到什麼目的？是寫給什麼樣的人看？當選定目標後，只需要套用框架，參考具體的指引，就能夠產出較精準的文件內容。
我希望這一則筆記能扮演 Reference 的角色，不需要嘗試記得所有內容，但當需要寫文件時，能先靜下來想想自己需要的文件類型，再回過來尋找對應的 Guideline 即可。
祝福各位從今天開始，都能夠以有效率的方式，產出精準的文件，透過文件來發揮更大的影響力、降低不必要的溝通成本，早日下班！
感謝你的閱讀，我們下次見！