我是一位軟體技術寫手，專門替公司撰寫產品教學文件。
下面要分享的工作技巧，就是如何寫一份內容清楚又好維護的文件。
- 如果你是軟體工程師、軟體產品經理，這個文件架構可以幫助你寫出好維護的產品教學文件。
- 如果你是業務、客服、或需要幫助公司紀錄業務知識的人，這個文件架構可以讓你對維護公司的內部知識更有概念。
我已經迫不及待的想要跟你分享了！
但首先，讓我先跟你分享一個故事。
在軟體業工作，我曾經以為更新產品教學文件，比開發新功能還要花時間。
每當團隊上線新功能，我就在擔心 “完蛋了…文件內容又要改了”。
然而有一天，我在網路上閱讀到 Divio Documentation System 的時候，我知道自己終於得救了。
Divio Documentation System 是一種撰寫軟體產品教學文件的框架，能夠節省文件寫作者大量的維護時間。
這套框架的核心精神是：
就像小朋友可以用樂高積木拼出不同的作品，產品經理/客服人員也能將文件內容分成不同模塊來維護。
當工程師要上線新的功能時，產品經理/客服人員只需要更新文件上的相關模塊即可。
這完全突破我的腦洞！
我不再害怕新功能的加入，因為更新教學文件變得輕而易舉。
下面是 3 個剛學習 Divio Documentation System 的人，最常問的問題。
寫文件問題 1. Divio Documentation System 有哪些模塊？
Divio Documentation System 將產品教學內容分成 4 大模塊。
分別撰寫：
文件模塊 1. Tutorials
指導使用者從 0 到 1 使用自家公司產品的流程。
以我負責的軟體產品–OwlPay 為例，我將公司戶使用者從 0 到 1 的步驟拆分如下：
Part 1. 啟用 OwlPay 服務
- Step 1. 註冊 OwlPay 帳號
- Step 2. 點擊「建立公司」建立您的第一家 公司
- Step 3. 設定付款途徑
- Step 4. 完成帳單繳費
Part 2. 開始使用 OwlPay 服務
- Step 1. 新增與驗證您的供應商
- Step 2. 管理訂單
- Step 3. 申請訂單對帳
- Step 4. 審核對帳單
- Step 5. 付款給供應商
你可以在 這個頁面，看到實際範例。
文件模塊 2. How-to guides
指導使用者針對特定功能，如何完成特定的任務。
我們以 iPhone 使用手冊 為例。如果你不會開機與設定 iPhone，可以在「開機和設定 iPhone」頁面一步步的教學。
這個模塊，專門紀錄完成特定任務的步驟。
文件模塊 3. Explanation
分享關於產品的相關知識。
例如國外知名金流處理廠商 (Payment Gateway)–Stripe，就撰寫了許多跟信用卡、防詐騙、電商結帳頁面…等相關的產品知識，詳情可以看 這裡。
這個模塊，可以讓使用者更加認識公司的產品 (進而產生好感並且持續使用)。
文件模塊 4. API Reference
指導使用者如何使用與串接產品對外的 API。
例如在 Notion API 中，就紀錄了如何使用 Notion API 來實現不同軟體之間的串接。
API Reference 寫的好，工程師串接服務沒煩惱。
在 Divio Documentation System 中，每一個模塊都各自紀錄特定的內容。
寫文件問題 2. 工程師上線新功能時，如何用 Divio Documentation System 更新文件
我們一起來想像一個情境。
「本次 Sprint (開發週期) 新增了 A 功能，在下一次 Sprint 又新增了 A-1 功能，在下下一次又新增了 B 功能，這樣教學文件要如何撰寫呢？」
可以分成 3 種狀況來處理：
狀況 1. A 功能
在 How-to guides 模塊中新增一頁，指導使用者如何使用 A 功能來完成任務。
狀況 2. A-1 功能
紀錄 A 功能頁面下，指導使用者如何使用 A-1 功能來完成任務。
狀況 3. B 功能
在 How-to guides 模塊中新增一頁，指導使用者如何使用 B 功能來完成任務。
按照上方做的好處，是「新增功能時」不用對舊文件的內容大幅修改 (我相信你體驗過文件要大改寫的經驗)。
把握一個原則：
新上線的功能跟既有功能有關嗎？
如果有關，就更新在相關頁面。
如果無關，就新增一頁。
這樣做，產品教學文件就很容易維護。
寫文件問題 3. 朱騏，實務上你如何使用 Divio Documentation System
我以自己幫公司撰寫的教學文件為例。
點擊 OwlPay Documentation，你可以看到 Divio Documentation System 分別出現在：
- Tutorials： 即為「從這裡開始」
- How-to guides： 即為「功能總覽」
- Explanation： 即為「名詞解釋」、「背景資訊」、「常見問題」
- API Reference： 即為「API 技術文件」
再來看一個例子。由 Python 寫成的開放原始碼 Web 應用框架–Djago，教學文件也是使用 Divio Documentation System 寫成的。
使用這套框架，就能幫助公司維護好產品教學文件
這篇文章我介紹了 Divio Documentation System 文件架構，並且回答 3 個剛學習的新手會問的問題：
- Divio Documentation System 有哪些模塊？
- 工程師上線新功能時，如何用 Divio Documentation System 更新文件
- 實務上我是如何使用 Divio Documentation System
下一次你有寫教學文件的機會時，趕緊來試用看看這套文件框架吧！
