文件的持續交付

在協同合作系統建制與導入一文中，有個段落在說明 文件管理，主要概念就是如何讓 文件的持續交付 這件事情，在組織裡能夠落實。底下文字整理自今年 02/22 的草稿

原由

春節放假期間，我做了一件很無聊的事情：

把 K8s 官方網站 (https://kubernetes.io/) 的 Source Code 爬過一輪。這個站是利用靜態網頁產生引擎 Hugo (雨果, Golang)。

註：不是把 K8s Source Code 看過一遍啊。。。別誤會XD

爬這個網站主要是想了解向 K8s 這麼大的組織 (400+人)：

是怎麼規劃、管裡文件的？
成員之間怎麼協作的？
文件品質是怎麼把關的？怎麼測試？
網站結構怎麼規劃的？
文件發佈是怎麼做的？

從中我學習如何規劃一個大型的文件架構，讓多人可以協作，然後學習裡面的流程與機制。

這段的思路主要源自於：Software Development Lifecycle

現況與問題

我個人的 Blog 是使用 Hexo (Node.js, 台灣人寫的) 的靜態網頁樣版引擎，個人使用尚可，但隨著我的文章數越來越多（現在約 170+ 多篇）效能問題也越來越明顯，每一次發佈要跑至少一分鐘以上，有時候還常常產生無窮迴圈的目錄結構，導致 node.js open too many file 的問題，還好類似問題，以前在用 Windows 寫扣時，很常處理類似問題。只是 Hexo 的效能問題已經漸漸浮上檯面。

Hexo 另一個問題是如何有效結構化文章的問題也浮上來，畢竟是個人的 Blog 使用，所以如果要多人協作，要有複雜一點的樹狀、分頁結構，就有點難搞，前端自己刻要花不少時間，現成的不能夠滿足。

文件的持續交付

所以我就想到直接找現成的來改，K8s 剛好是一個夠大，也夠複雜的範例，所以直接拿來研究了～ K8s Website 的 Source Code 除了一些 markdown 文件，還有用到很多模組化以及 code review 機制，最有趣的就是 LGTM 這個術語。

LGTM 是 Looks Good To Me 的縮寫，有人翻譯成 朕知道了，他是加速 Code Reivew 的機制，只要敲 LGTM 就會自動 Merge Code。

除了 LGTM，也了解到 Hugo 的效能之佳，了解到如何在本地有效測試網站 (Docker)，看到他的 CI/CD Pipeline 如何實作，如何做多語系的文件架構 … 等。文件跟程式碼一樣，同樣要有 Review，同樣要做持續整合、持續交付 …

所以從研究 K8s Website 的過程，就不難發現 Open Source 的團隊，如何在面對跨地區、跨時區、多人的團隊協作，這樣麼模式成熟且高效，產出的品質也是極高。這就是 Open Source 的力量，極強的渲染力，只要你想要，俯拾即是的知識與技巧，都在原始碼裡面。

其他參考

在此之前，我還參考過的是微軟 Azure 的文件，這個文件網站也是很不錯的參考指標，他同樣是 Open Source ，不過有點過於龐大，而且重點在於：目前微軟沒有把如何建置的方法 Open 出來，換言之，我只能看到內容，但無法在本地端進行測試與發佈，像用 Docker 或者自行發佈到自己的網站（可能是我不知道怎麼弄）。

社群共筆

最近在弄社群共筆，嘗試讓讀書會成員可以透過開放原始碼的協作方式，形成公開的協作模式，讓文件這件事情，可以有效地被組織、管理、分享。本來想選 hugo，不過他還是有點複雜，門檻較高，最後我選擇 mkdocs 作為主要文件產生器，先在 SRE 讀書會試行看看，相關資訊如下：

SRE 讀書會, Source

結論

其實工具只是其中一個落地的方法，更重要的是還有：

閱讀能力的培養
寫作能力的培養
組織能力的訓練
教育訓練，如人力招募系列文中的『到職：訓練』所提到的。

建立整個知識傳遞的循環、生命週期，在企業內部要形成知識傳遞的體系與系統。核心概念跟軟體開發週期一樣，和 持續交付 一樣，同樣是有原始碼、有產出物、有持續整合、有測試、持續交付等。

文件的持續交付

原由

現況與問題

文件的持續交付

其他參考

社群共筆

結論

延伸閱讀

站內延伸

學習、寫作、閱讀系列文章

學習、寫作、閱讀系列文章

文件工具

Comments

About

著作

演講

Facebook

AWS Certifications