Docs as Code 與知識管理系統

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

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

本文轉貼自 Huanlin's Notes

目前我是用 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!

延伸閱讀

• Docs as Code by Eric Holscher

• Crafting Docs for Success: An End-to-End Approach to Developer Documentation by Diana Lakatos