寫出高品質軟體教學手冊的秘笈：來自 2 年軟體技術寫手的實戰經驗，解決客服人員、產品經理在維護產品文件的煩惱

我是一位軟體技術寫手，專門替公司撰寫產品教學文件。

下面要分享的工作技巧，就是如何寫一份內容清楚又好維護的文件。

• 如果你是軟體工程師、軟體產品經理，這個文件架構可以幫助你寫出好維護的產品教學文件。
• 如果你是業務、客服、或需要幫助公司紀錄業務知識的人，這個文件架構可以讓你對維護公司的內部知識更有概念。

我已經迫不及待的想要跟你分享了！

但首先，讓我先跟你分享一個故事。

---

在軟體業工作，我曾經以為更新產品教學文件，比開發新功能還要花時間。

每當團隊上線新功能，我就在擔心 “完蛋了…文件內容又要改了”。

然而有一天，我在網路上閱讀到 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 個剛學習的新手會問的問題：

1. Divio Documentation System 有哪些模塊？
2. 工程師上線新功能時，如何用 Divio Documentation System 更新文件
3. 實務上我是如何使用 Divio Documentation System

下一次你有寫教學文件的機會時，趕緊來試用看看這套文件框架吧！