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

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

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

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

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


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

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

然而有一天,我在網路上閱讀到 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」頁面一步步的教學。

開機和設定 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 寫成的

Django 的教學文件框架
Django 的教學文件框架

使用這套框架,就能幫助公司維護好產品教學文件

這篇文章我介紹了 Divio Documentation System 文件架構,並且回答 3 個剛學習的新手會問的問題:

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

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