我是一位軟體技術寫手,專門替公司撰寫產品教學文件。
下面要分享的工作技巧,就是如何寫一份內容清楚又好維護的文件。
- 如果你是軟體工程師、軟體產品經理,這個文件架構可以幫助你寫出好維護的產品教學文件。
- 如果你是業務、客服、或需要幫助公司紀錄業務知識的人,這個文件架構可以讓你對維護公司的內部知識更有概念。
我已經迫不及待的想要跟你分享了!
但首先,讓我先跟你分享一個故事。
在軟體業工作,我曾經以為更新產品教學文件,比開發新功能還要花時間。
每當團隊上線新功能,我就在擔心 “完蛋了…文件內容又要改了”。
然而有一天,我在網路上閱讀到 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
下一次你有寫教學文件的機會時,趕緊來試用看看這套文件框架吧!