此为历史版本和 IPFS 入口查阅区,回到作品页
Benjamin
IPFS 指纹 这是什么

作品指纹

流程標準化-以腳本取代文件

Benjamin
·
·
寫技術文件不難,要讓所有人都能看懂說明有點難,想統一不同成員寫的技術文件格式和風格相當困難,想讓其他人持續更新文件,維持文件有效性更是難上加難。因此,我不寫技術文件了。 這篇文章寫給對系統管理有興趣的人,也許有些設計的想法可以參考。

技術文件是指專案的共用資料夾之中的執行記錄,大多數是以前的某人在處理一項工作完成之後留下的,可以供其他人處理類似的任務時參考。

然而,「技術文件是經過實證,確認正確的說明書」這個前提並不成立,可能受程式版本不同的影響導致用法不同,或者是說明不完整,光從文件沒辦法理解在哪輸入參數,或如何進入下個步驟。甚至還有一些只是把研究的過程中參考過的網路文章貼上,但內容其實是錯的。

為了讓其他人判斷文件的有效性,我在參考過確認有效的文件末留下記錄:「Benjamin: 2022/6/30 設定主機 db1 參照上方步驟完成,確認可用」,但是這種行為並不是標準流程,其他人也不知道可用這個判斷。

此外有些人在發現缺少文件或文件錯誤而上網搜尋資料,解決問題之後也不會想寫文件或更新文件。「我已經知道怎麼做了為什麼要寫下來,有需要問我就好啦?」這樣的結果通常就是未來當事人自己也忘記細節如何執行,或者是離職時沒想到要交接(「趁我還在公司要問的趕快問喔」這種話得到的反應通常是不知道要問什麼,實質廢話),曾經花費的時間沒能對未來發揮作用,我覺得這點非常可惜。

所以,我也不想寫文件了。


就像上次事情結束之後的反思,我只要把這次使用的步驟完整寫上去就行了嗎?或許不只是寫的內容正確,有沒有什麼辦法可以提高執行速度,降低錯誤發生的可能,還能夠在流程需要調整的時候不會忘記更新呢?

我的結論是這樣的:讓文件改為可以執行的腳本不就好了?

只要前次執行是透過腳本完成而結果正確,就可以證明腳本的正確性;其他人負責工作的時候只要執行腳本就能完成,省下來回剪貼執行指令的功夫,更甚者如果想了解各步驟具體使用的指令也可以參考腳本內文;萬一腳本有錯,或者需要修改輸入值、修改輸出格式的時候,只要要求「必須使用腳本完成工作」,就能確保腳本的功用與現在的流程相符合,想像起來真不錯。

雖然列出這些優點,不過也不是什麼都適合腳本化執行,腳本化主要適用的情境是重複而且不需要太多人工判斷的流程。

目前想到唯二的缺點是腳本化的開發時間成本,以及對使用者的技術要求,根據實際情況可能因這些而放棄開發。

首先,腳本化除了確認腳本功能正常之外,還需要以好讀好維護的方式開發,並根據情境加上執行記錄或其他判斷邏輯,因此腳本化的過程需要相當的時間進行測試和修改。除非剛好有空或是很有經驗否則一般專案很可能想想就覺得不划算,維持原本看文件執行的方式了(我的情況是前者,維運的期間沒事發生就需要找事做)。

包含前面說的人工判斷與否的條件,有些時候想把人工判斷寫成腳本處理也不是不行,但是可能讓腳本開發過於費時,而且不好維護,最後選擇不開發。因此第一點說白了還是時間和人力成本的取捨,再決定如何使用。


關於對使用者的技術要求,考慮到原本參考文件執行的時候也應理解各指令的功用,因此看懂腳本各步驟指令的功能本來就是必要的,所謂的技術要求主要是針對後續維護的部分,畢竟腳本的語法和其他語言也有所不同,如果沒辦法修改,功能會局限在現有的範圍內。

簡單分享幾個腳本執行的樣子和設計想法,不過程式碼就不方便分享了。


前一篇提到的 SSL 憑證申請為例,根據使用的情境分為不同的功能,當操作者在看不懂腳本內容,不明白該如何呼叫功能的時候執行,會顯示參數的提示:

有格式和參數的種類

在參數正確,功能執行的過程中也會輸出文字訊息,顯示執行的進度:

過程的執行記錄

另外由於申請憑證不只是腳本本身,還有事前準備的和過程中產生的檔案需要保存,適合在固定一台機器上執行,這部分也透過另一套文件說明腳本所在的主機與目錄資訊。


由於架構的需求,一次程式更新版本需要同步到多台機器再重啟服務,為了省去一次一台花費的大量時間和輸入錯誤的風險,公司的前輩在今年上半年開發過程中寫了一鍵更新各機器服務的腳本,簡稱一鍵布版腳本。包含備份、上傳新版本、重啟等各台機器共通的步驟皆可一氣呵成,只需 10 秒就能完成原本需 10 分鐘以上的工作,而且不會出錯。

不過後來維運的期間依據更新內容不同,但每次更新同步的數量和對象可能有所不同,因此需要對原有腳本做些修改。為了避免執行錯誤而加入確認的步驟。

執行過程會將目標IP列出,確認是否執行

在操作期間根據進度顯示畫面的同時,也會把這些資訊寫入記錄檔,方便後續追查,使用起來也比較安心。


上面說的都是在固定一台機器上執行的腳本,新電腦設定環境的情況就會透過複製腳本到各主機上執行的方式了。

有的時候腳本化不只是為了把多步驟的複雜流程變簡單,而是要確保不會遺漏某個步驟,並盡量使操作過程更容易使用。

建立使用者的腳本程式碼

以圖中,邏輯最簡單,其實只要兩三行指令就能完成的新增使用者為例,除了建立使用者之外,還加上事前的確認使用者不存在,事後的是否設定為管理員、設定使用者密碼,以及用自定義的方法測試管理員權限正常。

這種做法可以讓執行過程中不用加上額外的麻煩就能完成檢查步驟,而且後續如果有稽核或是其他需求要確認設定方式的話可以直接提供腳本做參考,不必查找機器的執行指令。


其實有很多腳本的開發並不是打從一開始就決定寫成腳本,甚至有些時候還是重複做了幾次同樣的操作之後才想到腳本化的可能性。而這個想到並實作的原動力,就是「我不想用這麼麻煩、浪費時間的方式做事」,也就是想要偷懶。

只要對現有處理的流程抱持著懷疑,相信有更好的方式存在而非一昧地盲信照做,不管是腳本化或其他方式都行,用你自己想得到的、覺得好用的工具進行改進,在自我成長的同時也就會發現有些事情其實可以不用那麼麻煩。

CC BY-NC-ND 2.0 授权