文件的持續交付


協同合作系統建制與導入 一文中,有個段落在說明 文件管理,主要概念就是如何讓 文件的持續交付 這件事情,在組織裡能夠落實。底下文字整理自今年 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 讀書會試行看看,相關資訊如下:


結論

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

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


延伸閱讀

站內延伸

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

文件工具


Comments