Docs as Code 與知識管理系統

Tags:

你任職的公司裡面有沒有使用現成的知識分享平台或知識管理系統？例如 Confluence、Document360 等等。

更新：後來從我的臉書貼文下方收到一些網友的分享，得知有些公司是用 Notion、OneNote、Google Docs、Azure DevOps 的 wiki 等等。也很高興看到有人的公司是採用 monorepo + markdown 的作法，也就是稍後會提到的 Docs as Code。

目前我是用 markdown 編寫技術文件，搭配 Git workflow 來自動建置與發佈文件至網站。我寫的文件主要是軟體系統的 user guide 以及 API tutorial。像這類正規的產品文件，許多開放原始碼專案也都是採用類似的作法，例如 Kubernetes Documentation，以及這篇筆記所在的網站（使用 Hugo 建置）。

然而，使用 markdown 撰寫文件，並搭配靜態網站生成工具（如 Hugo）來建立技術文件網站，對企業內部需要知識管理的情況適用嗎？它能夠滿足企業對 KMS 的需求嗎？對此問題，我並沒有十分確定的答案，僅透過這篇筆記梳理目前的想法。

簡單起見，接下來的討論，會把 markdown + Git workflow 的文件製作方式稱為 Docs as Code，即 Documentation as Code 的簡寫。

Docs as Code

Docs as Code 指的是用跟寫程式一樣的工具來寫文件。我用來寫文件的編輯器是 VS Code，檔案內容的格式則為 markdown。

優點：

  • 採用 markdown 編寫，語法簡單、排版風格容易趨於一致。
  • Markdown 是文字檔案，有許多工具可以對檔案內容進行處理。例如文字搜尋替換、整批翻譯、移轉至其他文件平台等等。
  • 搭配 Git workflow 在團隊中實施 review 和 approval 程序，有助於傳遞知識、確保文件品質。
  • DevOps team 本來就熟悉 Git 操作以及相關流程，故很容易一起加入文件協作的行列。如果有時間和興趣，團隊成員皆可自由貢獻至文件庫，亦可藉此發現潛在的 technical writer 人選。
  • 避免 vendor/platform lock-in。因為文件是以 markdown 檔案的形式保存，未來若要改用其他文件工具或平台，可輕易移轉既有內容，減少重工，從而確保先前製作文件的心血不會白費。
  • 有很多開放原始碼的解決方案可供選擇。

缺點：

  • Markdown 語法雖然簡單，但是對於沒寫過的人來說，還是有一點學習門檻。一旦拿來跟 WYSIWYG 介面的文件管理平台比較，親和力就輸了一截。（熟悉 markdown 的人應該會覺得 markdown 才更親切吧。）
  • 搜尋能力僅限於「這個文件網站」，也就是同一個 Git repository 內的文件。如果企業內部想要建立一個統一的知識管理平台，Docs as Code 方法很難做到跨站搜尋和跨產品搜尋，除非把所有產品的文件全都放在同一個 Git repository（也就是同一個網站）。
  • 使用者 feedback 和互動功能通常比較陽春。如果是封閉的企業內部網路（防火牆阻止外連），相關功能甚至完全不 work（例如無法使用 giscus 留言板）。
Tip
如果擔心 markdown 的表格不好編輯，VS Code 有一個方便好用的 extension 叫做 Excel to Markdown table。只要把 Excel 文件的儲存格區塊複製到剪貼簿，然後到 VS Code 中按 Shft+Alt+V 貼上，就是 markdown table 了。

Full-blown KMS

現成的 KMS，我只有用過 Confluence。這裡僅以我個人有限的使用經驗來說說這類 full-blown KSM 的優缺點。

現成的 KMS 最大優點就是豐富的功能。通常有這些：

  • WYSIWYG 文件編輯器，高親和力，隨時可寫。
  • 所有文件全都集中在一個平台，方便管理和搜尋任何文件。
  • 更好的 user feedback 與互動功能。
  • 文件的權限管理功能。
  • 文件的統計分析功能，例如某一篇文章的點閱次數。

就我所知，Document360 除了上述功能，還有：

  • 支援 markdown 編輯器。（這個我喜歡！）
  • 可製作美觀的 API reference manual。
  • 可讓管理者自行定義文件的 review 與 approval 流程。

我認為支援 markdown 編輯器對 KMS 非常重要。因為如果只提供 WYSIWYG 編輯器，每個人寫出來的文件可能都有不同的排版風格，容易導致文件內容格式花俏、凌亂。

此外，文件的 review 和 approval 也很重要。因為 KMS 的操作介面通常很容易上手，且隨時瀏覽器打開頁面就能寫。這很容易產生一個現象：許多文件的品質就跟草稿差不多，例如一堆錯字、沒有為讀者設想閱讀順序，甚至各文章之間也沒有相互關聯。這些問題都和 KMS 工具本身沒有直接關聯，因為關鍵在於寫文件的人是否想要寫出易讀易懂的文件，以及作者本人是否有相關的寫作訓練或經驗。然而，KMS 工具隨時可以寫點東西，這樣的靈活性也多少是促成這種現象的間接原因。

缺點：

  • Vendor/platform lock-in。一旦採用某個廠商的 KMS 解決方案，所有輸入至該平台的內容就會綁在上面。萬一日後發現這平台不好用，想換到另一個 KMS，可能要費不少工夫把既有的文件撈出來，再轉入另一個工具平台。
  • 可能有額外費用，例如支付給 KMS 軟體廠商的年費。

該選哪個？

我認為現成的 KMS 平台很適合企業內部用來蒐集與管理零碎片段知識。這類片段知識通常不會太要求作者字斟句酌，只要有點到關鍵的技術 know-how，能讓讀者解決特定問題就好。雖然它也一定能製作出品質優秀的文件，但其主要關鍵還是在寫作的人。

採用 markdown 來編寫技術文件的 Doc as Code 方法，則很適合撰寫單一產品或一整套相關產品的正規文件。至於能夠在一個 Git repository 放進多少個產品的技術文件，這不好估算，我沒有一個比較客觀具體的數字。就我目前的經驗來說，把三到四個相關產品的 user guide 和 API reference manual 放進同一個 Git repository，跑 CI/CD pipeline 並不至於花太長時間（因為 Hugo 的執行速度超快），生成的網頁也沒有碰到搜尋效率不好的問題。

若在企業內部採用 Doc as Code 方法來建立各產品的文件，最終大致會是這個樣子：每一個產品文件就是一個網站，有自己的網址；各產品文件之間若有關聯，則會在文件中加入交叉參考連結。由於工具內建的 local search 功能無法在企業內部做到跨站搜尋，也只能以交叉參考連結來把相關的產品文件串起來。

結語

無論採用 Doc as Code 方法還是現成的 KMS，知識管理的關鍵主角應該是內容。有了好的內容，再搭配方便強大的工具，才能真正起到傳遞知識和知識管理的作用。

怎樣寫出好的文件內容？關鍵還是在人。

Keep writing!

延伸閱讀


先這樣，也許有空時會再更新。   我的其他站點：      

Last modified: 2024-09-01