I'm Chi
0
  • 登入
  • ✍️ 部落格
  • 🧑‍💻 我的服務
    回主選單
    • 業配合作
    • 1 對 1 寫作教練
  • 🎥 線上課程
  • 👥 講座活動
  • 📮 聯絡朱騏
  • 🎤 課程與企業培訓
    回主選單
    • 所有主題
    • 職場個人工作術|時間管理
    • 職場個人工作術|卡片盒筆記法
    • 職場個人工作術|ChatGPT 文案應用
    • 軟體開發實務|技術文件寫作
  • 註冊
  • 登入
  • 0
I'm Chi
  • ✍️ 部落格
  • 🧑‍💻 我的服務
    業配合作 1 對 1 寫作教練
  • 🎥 線上課程
  • 👥 講座活動
  • 📮 聯絡朱騏
  • 🎤 課程與企業培訓
    所有主題 職場個人工作術|時間管理 職場個人工作術|卡片盒筆記法 職場個人工作術|ChatGPT 文案應用 軟體開發實務|技術文件寫作
  • 文章總覽
  • 分類
  • 🧑‍💻 工作 (182)
    • 工作生產力 (45)
    • 數位工具 (33)
      • Obsidian (6)
    • 個人品牌 (55)
    • 一人公司 (30)
    • 講師教學 (10)
    • 商業觀念 (2)
  • ✍️ 寫作 (152)
    • 網路寫作 (133)
    • 文案 (12)
    • 技術寫作 (1)
  • 🧠 學習 (153)
    • 自我成長 (67)
    • 讀書心得 (39)
    • 個人知識管理 (40)
    • 復盤 (6)
  • 🤖 AI (52)
    • ChatGPT (38)
    • Claude (8)
職場技巧 (2) Notion (1) Obsidian (0) Q&A (1) AI (20) ChatGPT (15) 靈感 (2) 日記 (1) 第二收入 (17) 提問 (3) 框架 (2) 網站經營 (1) 習慣 (3) 檢查清單 (1) YouTuber (1) 目標 (3) 電子報 (12) 正念 (1) 卡片盒筆記法 (4) MailerLite (6) 文案 (3) 人物 (24) Podcast (1) 簡報 (1) 出書 (3) 筆記軟體 (3) Lean Writing (9) 數位產品 (12) 專案管理 (2) 導覽 (1) 定位 (3) 模版 (4) 新手 (10) 技巧 (5) 策略 (1) 反思 (2) 職場上班族 (5) 筆記 (4) MidJourney (1) 電子書 (2) 1對1諮詢 (1) 讀書會 (3) 時間管理 (3) 說故事 (7) 自動化 (1) 訪談 (1) 個人知識管理 (1) 圖解 (1) 職涯 (1) 思考 (1) 行銷 (1) 痛點分析 (0) 目標讀者 (1) 需求分析 (1) 原則 (1) 溝通 (1)
  1. 首頁
  2. 部落格
  3. 寫出高品質軟體教學手冊的秘笈:來自 2 年軟體技術寫手的實戰經驗,解決客服人員、產品經理在維護產品文件的煩惱

學習 Divio Documentation System

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

2024 Sep 26 技術寫作
內容目錄
  1. 寫文件問題 1. Divio Documentation System 有哪些模塊?
    1. 文件模塊 1. Tutorials
    2. 文件模塊 2. How-to guides
    3. 文件模塊 3. Explanation
    4. 文件模塊 4. API Reference
  2. 寫文件問題 2. 工程師上線新功能時,如何用 Divio Documentation System 更新文件
    1. 狀況 1. A 功能
    2. 狀況 2. A-1 功能
    3. 狀況 3. B 功能
  3. 寫文件問題 3. 朱騏,實務上你如何使用 Divio Documentation System
  4. 使用這套框架,就能幫助公司維護好產品教學文件

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

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

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

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

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


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

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

然而有一天,我在網路上閱讀到 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

這個模塊,專門紀錄完成特定任務的步驟。

文件模塊 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 的教學文件框架

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

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

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

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

 
朱騏
 
朱騏 (Henry)

職場寫作教練,提供一對一深度客製化的網路寫作課程。

幫助你提升寫作技巧,讓你在網路上被看見並吸引潛在客戶。

若想要獲得更多寫作秘訣,歡迎在下方訂閱我的電子報 👇

  • 分享此文章
0則留言

相關文章

【MidJourney 系列 – 1】不知道如何使用 AI 繪圖工具 MidJourney 嗎?掌握 5 個結構寫好 MidJourney Prompt,畫出自己想像中的圖片

  • 2023 Feb 07

《在寂寞的夜裡提起筆》 讀書心得 | 想要開始寫作卻不知從何下筆?這本書告訴你答案!

是不是常覺得寫作很難,甚至害怕提筆?別擔心,日本作家古賀史健的《在寂寞的夜裡提起筆》提供了10個實用秘訣,讓你重新愛上寫作。從克服負面情緒、細節描寫到用日記反思生活,這本書教你如何透過文字整理思緒、表達自我。

  • 2025 Jan 17

如何重複利用你創作過的內容? 5 步驟把破碎的筆記積累成一本書

  • 2023 Jan 10

不知道自己的文章到底要寫給誰看嗎?

你在寫作的時候,曾經苦惱過不知道要寫給誰看嗎?在網路上寫作的時候,別急著馬上「動手寫」。 你應該先想清楚 4 個問題 → (1) What 我要寫「什麼」 (2) Who: 要寫給「誰」看,他們遇到什麼「問題」 (3) So that: 所以看完後「有什麼好處」 (4) Credibility: 為什麼我有寫這篇文章的「資格」

  • 2023 Sep 15

想提升你在「個人品牌」的經營技巧嗎?身為職場上班族的你,絕對要聽這個 Podcast (沒時間的話,先聽這 5 集就對了)

  • 2023 Dec 11

如何寫教學文,把自己的經驗分享出去 ?

  • 2022 Oct 10

關於朱騏

  • 🗞️ 電子報

聯絡我們

  • Email: admin@chichu.co
  • 聯絡電話: 0939513266
  • 地址: 220 新北市板橋區三民路2段81巷27弄23之1號4樓
  • 公司名稱: 知騏然有限公司
  • 統編: 93719055
  • 隱私權政策
COPYRIGHT© I'm Chi All rights reserved | Powered by 路老闆