今天的文章不是一個技術文，反而是探討身為一個軟體工程師，該怎麼撰寫相關的技術文件

鑑於 WFH (Work From Hoem) 習慣的興起，人與人面對面的溝通減少，這意味即時的訊息傳遞變少了，取而代之的是非同步的訊息傳遞，簡單來說就是技術文件。

好的技術文件能夠讓需要的人快速找到問題，解決疑惑，但是一個好的技術文件到底該怎麼寫，這部分其實非常困難，並不是向程式碼一樣可以 copy&paste 馬上看到成果的，反而是需要時間練習，將整個過程與思路消化起來，用自己習慣的語言與形式將其撰寫出來。

首先，作者非常推崇由 Google 撰寫的系列文章，Tech Writing Course，整個課程內容不到兩小時，從不同章節來跟大家分享如何撰寫技術文章

接者撰寫技術文章時，作者個人是喜歡 divio 這個平台，不過更重要的則是其推薦的分類模式，根據內容分類成四大項

1. Tutorials - 學習導向
2. How-To Guides - 問題解決導向
3. Explanation - 深度理解導向
4. Reference - 資運分享導向

Google: https://developers.google.com/tech-writing
Divio: https://www.divio.com/

最後寫作語法方面，作者認為寫出一個能夠被有效搜尋的文章是非常重要的，譬如透過 word 等方式上傳檔案到系統中反而是一個不利於搜尋的方式。
取而代之的是，作者認為可以採用 Markdown 類似的語法作為基礎去撰寫文章，這種方式對於維護與撰寫都相對容易

今天有任何 Diagrams 的畫圖需求，可以考慮使用 Mermaid 這套解決方案，對於 GitLab/Azure 的使用者來說，已經內建其中。 GitHub/Atlassian Confluence 則有相關的 Plugin 可以安裝使用

最後則是文章的樣版內容，針對特定的文章格式，已經有不少的範本可以參考，透過這些範本可以更清楚的去描述你的內容，讓整體文章看起來更佳簡潔與流暢

1. Software Architecture Review Template
2. Architecture Decision Record Template
3. Incident Postmortem Template
4. DevOps Runbook
5. Decision Template
6. Writing Guidelines
7. OKR Template
8. Etc.

有興趣的點選原文學習更多
https://medium.com/better-programming/best-practices-when-documenting-your-code-for-software-engineers-941f0897aa0

下禮拜一在 Youtube 有一支影片來閒聊回顧的細節，在這之前還是有文字版的紀錄一下

2020 年回顧，雖然是個疫情擾亂的一年，但仔細回顧還是做了滿多事情的

► 個人
・部落格寫了 26 篇文章
・建立 Youtube 頻道，上傳了 32 部影片，半年累積 4 萬訂閱及 130 萬總觀看量
・「區塊鏈懂不懂」小聚講座分享
・受邀 MOPCON 成為論壇講者
・Side Project 由虧轉盈，平均每月收穫 200 USD
・與自己的愛車參與改裝拍攝
・寫了一本「如何經營工程師 Youtube 頻道」的小書

► 工作
・參與約 10 場的面試，從面試官的角度思考流程以及規劃尊重人才的模式
・成為目前 Ruby 的 Team leader
・將 gitea 轉移到 gitlab，與 DevOps 協助導入更完善的 CI/CD flow
・成功建立每週五工程部分享會的文化
・將金錢相關的 unit test 補齊
・學習 K8S 相關的知識

今年沒出國，錢拿去買了 shoei 祭典帽、做了整套引擎、買 iphone 12 pro、偽出國澎湖、台南玩耍

然後愛上和朋友一起玩 LARP 劇本殺

值得檢討的是，想做的事情太多，反而分散了火力，雖然都是自己親力親為，但也顯得火力不足，無法專心在某個地方上，反而想越深卻越廣了，新的一年要定義更明確的目標並把其他事物分擔出去才是

覺得自己在這一年的技術能力沒有明顯成長的突破，但反倒是個人的品牌經營跟行銷成長了很大一塊，好像在成就的部分，總有遺憾和新鮮感拉扯

但對整體在年初許的願望，「加強開源」這個方向確實是做到了，而且超出我的預期

謝謝每一個支持的朋友，今年忙到很晚才寫回顧，但不變的是更努力的提昇自己與突破限界，在新的一年我一樣會認真做自己，並且完成給自己的目標

然後看著另一半也在努力進步，絕對是種無比的榮耀與超飽滿的精神糧食 😆

隨者資安意識的提升， Container Image 的安全性檢查變得愈來愈重要，最基本的想法就是針對 Image 本身去檢查是否有任何已知的 CVE 與 vulnerabilities，透過這類型的機制來確保我們要部署到生產環境的 Container Image 是足夠安全的。

目前至少有三種方法可以來達成這目標，第一種是直接使用相關的 CLI 工具掃描，第二種是將工具整合到 Container Registry 中，根據情況自動掃描，第三種則是將工具整合到 CI/CD pipeline 過程中，只有符合標準的 Container Image 才有資格被推到團隊所使用的 Container Image。

本文作者透過 Trivy 以及 GitlabCI 等工具來示範如何於 CI/CD pipeline 中完成 image 的安全性檢查(也就是方式三)。

# 重點整理
1. Trivy 掃出來的安全性有四種，分別是 Low, Medium, High 以及 Critical
2. Trivy 本身不定義什麼樣的結果叫做安全或不安全，完全是根據使用者自己決定。作者認為這個標準取決於團隊對於資安的重視性。範例中，作者定義只要有任何一個 Critical 等級的安全性漏洞，就將該 Image 視為不安全
3. 透過 Gitlab CI 的流程，來建置 Container Image，並且透過 Trivy 掃描，如果不符合安全定義就透過 exit-code 來結束該 stage，同時也會將 Trivy 的掃描結果給一併上傳。

如果對於(2)透過 container registry 來掃描的，可以參考我今年針對 ITHOME 鐵人賽所撰寫的文章: https://www.hwchiu.com/ithome/2020/registry/day21.html

原文：
https://medium.com/alterway/adding-image-security-scanning-to-a-ci-cd-pipeline-2faff072d