已徵得原作者同意，以 CC BY-SA 4.0 授權進行本文的翻譯。

原文

連結在此。
Hacker News 討論。

作者

James Munns，Rust 工具 postcard 的作者與維護者。他的專長為嵌入式系統與 Linux，現職為顧問。他的 LinkedIn 於此。

本文翻譯開始

系統工程實踐，或「詹姆斯賴以維生的心法」

譯註：原文的 Systems Engineering 本身帶有相當的模糊性，譯為系統工程實踐或有可議之處。譯者追求速度之下，探究作者原意應相去不遠，所以訂定譯名如此。

我是一個顧問。我通常參與包含硬體（電子零件或機械元件）的專案，但通常是輔導其中的軟體部份：微處理器的程式碼、桌面系統的東西、有時也處理些伺服器端的東西。有時候我得負責動手實作特定的項目，如一隻驅動程式的概念驗證（proof of concept）；有時我參與評估如何導入 Rust；又有時我輔導客戶，將原型（prototype）轉換為產品。

結果，我的時間通常都花在幫助人們導入系統工程實踐。這有點像「如果你只有榔頭，什麼東西都像釘子」，也可能我自己嗑了太多系統工程實踐的藥。但無論如何，這招一直都有效且幫得上忙，所以我就繼續揮動這榔頭吧。

譯註：可參照工具定律。

我可能有天會想要以此為題寫一本書，而本文即是尚未清晰爬梳過的一堆想法的起點。我現在（還）沒有可以賣給你的祕笈，本文也沒有任何無敵的通用解答。這裡有的，只是一些可能對你手邊的專案有幫助的一些思考方向。

我並非流程的忠實信徒，也不是把系統工程實踐這一套當神在拜。有時實踐一小部份或許就大有助益，有時（尤其如果你的專案與安全相關）你得一次把所有事情做到位。做到你覺得對的程度即可。如果這套沒用了，那就找別的方法來嘗試。理想上，接下來我要介紹的概念應該會讓你像是投資了績優股，立即開始帶來一些紅利。

何謂「系統工程實踐」？

也許美國太空總署或是哪個機關會有更好的定義吧，不過對我來說，這個實踐涵蓋以下兩個課題：

1. 能夠明確地回答，你以及你的團隊在打造的是什麼東西
2. 能夠明確地回答，你以及你的團隊如何打造它

看起來很簡單對吧？嗯，有時候很簡單。

在哪裡會出事？

當人們參與一個多人專案，其中各人來自不同背景（如：有些做軟體、有些做硬體、有些負責管理、有些負責產品等）的情況下，在團隊與組織之中，大家往往將上述的「打造什麼」與「如何打造」問題拋諸腦後。

也許是，你的專案規模變得比前一個還大；也許是，你打算處理一個你並不熟悉的新領域裡的問題。一開始很簡單的事情快速變得複雜起來，而且無論你如何努力，終點線都沒有因此更接近一些。

就像其他許多的「最佳實踐」一樣，你幾乎總是可以順風順水地度過困難，如果你面對的是較小規模的專案，或是僅與較小規模的團隊合作。但隱藏的問題可能帶有 O(n^2) 甚至指數等級的複雜度，一開始都好好的，直到某天你終於追不上規劃的進度了，拖延一個月、一季、甚至以年計算。

為什麼人們不著手進行系統工程實踐？

每個人的功力可能各有千秋，但我發現一般來說軟體工程師們很少受過正規訓練以解決上述的問題。他們會拆解問題，希望能夠小範圍地解決，但他們面對團隊規模的問題的時候，往往缺乏好的手段去切分問題。

在傳統的工程領域如電子與機械，工程師們比較可能有系統工程實踐相關的經驗，不過他們未必徹底理解為什麼有那些實踐的方法。

這表示，如果你的組織中沒有系統工程實踐的文化，那通常也不會有人能夠協助導入了！這也常常是我的切入點。不需要等到火燒屁股，人們就應當可以開始受惠於導入一些系統工程實踐。有時候對人們來說，整個專案流程更可預測一些些、更少一些「驚喜」，其實就很不錯了。

嘿，你的系統工程實踐介紹還有定義還是太模糊了！

好吧，我只是想試著簡單扼要。讓我們延展一下實質內容...

能夠明確地回答，你以及你的團隊在打造的是什麼東西

譯註：原文為 Be explicit about what you are building。譯者才疏學淺，不知道 Be explicit 到底該怎麼真正在中文對應到一個動詞才最通順？所以翻譯時假想了顧問詢問「你的團隊在打造什麼？」而受輔導者必須回答的情境。事實上，結合作者後續的內容展開，明確一詞所對應到的動作包含文件紀錄、呈現、口語描述、溝通等等。

正式來講，這個提問包含了以下主題：需求、規格、架構、以及驗收標準。每一個主題都儘可各自展開成文，但我打算留待之後再論述。非正式的來講的話，這個提問的意義在於，每一個團隊中的成員都應該非常清晰地知道這個專案中該做的事情是什麼。

所以，本文中我將會強調這件事情很多次，那就是如果資訊沒有被寫下來，那麼那些資訊就不存在。

• 你永遠不知道兩個人是否擁有相同的心智模型，多人的情況自然更糟。
• 你永遠不知道你自己的心智模型是否一致；有時候你覺得一切都很合理，但試著寫下來之後，就發現其中的矛盾。
• 你無法保證你對事物的理解不會隨著時間改變，或是遺忘了部份的心智模型。

解法就是你必須寫下你的專案應該做的事情，不管是程式碼、硬體或其他什麼資訊都是如此。這不需要非常的正式。用 markdown 文件、用 Words、用 Excel、用什麼都沒差，總之寫下來。在各種媒體之中遷移資訊，總是比一開始要一次歸檔大量資訊容易。

不管你使用什麼工具，對於你的整個團隊來說，接下來的重點是：唯一真實來源是什麼？如何閱覽它？如何能夠隨時存取它？

譯註：可參考維基，目前沒有權威的譯名，但常見的簡寫為 SSOT 代表 Single Source of Truth）。簡單的解釋是，所有資料都應該只有一個正本，其他的存取皆為參照。

比方說，如果你把專案規格書以 git repo 的形式存放，而你的專案經理不知道如何存取 git，那麼你維護的規格書就沒有用。如果你的公司導入了一套華麗的管理工具，你並利用它來存放專案規格書，但公司並未取得所有人都能使用的授權條款，那麼這份規格書也同樣毫無用處。

設想，人們對一個功能感到疑惑「咦，這個的原理是什麼？」之後，可能採取的動作為以下兩種情境：

1. 查閱說明文件
2. 亂猜（存在部份誤會甚至完全錯誤的理解）
   僅僅在第一種動作所需的時間小於第二種動作的時間的時候，說明文件的存在才有意義。

說明或規格之類的參考文件，僅僅在人們可以輕鬆查閱的時候有意義，因為存取文件並查閱的力氣理當小於為某些系統行為爭辯，當然更應該小於召開會議以使得所有人的資訊同步。

要讓這套作法成功，我們需要下一個規則：你的規格文件必須是精確的。詳細考究的話會有點怪怪的，精確這個形容在「系統將會這麼做」和「系統是這麼做的」之間應該怎麼確定下來？這是另外一個可以獨立成文的主題。無論如何，無論何時，你的規格文件必須是精確的。

譯註：原作者交叉混用「需求」與「規格」，但譯者認為沒有必要加入這個額外的困擾因子，統稱規格或是規格文件。

如果規格文件描述「這個系統執行 X 行為」，那麼電子工程師就不需要與軟體工程師溝通，也能夠在心裡把這個敘述當作事實；業務部門可以引用這個敘述到行銷材料之中，而不會有任何問題。如果兩個或更多人對於系統應有的行為產生認知的歧異，那麼規格文件應扮演仲裁的角色。

總之，規格文件應該要能夠容易閱讀、查找、並從中獲取資訊。

有些業內人士紀錄規格文件的工具是像 JIRA、或是 Github Ticket 系統。那些紀錄，前後來講時間都跨度都很大。人們該怎麼知道哪一份是正確的？哪一份是最新的？如果你對於系統有個類似「系統一次可以處理多少個東西」這樣的問題，你該怎麼找到答案？

基於上述理由，我認為只應該維護一份文件且持續更新它。如果這份規格書不清楚，甚至有明顯的錯誤，那每個人都該知道怎麼樣去改進它。

需求、規格文件、系統行為文件這些東西應該要像是具有生命一般成長。就算你依照「瀑布式開發」模型行事，你對於系統的了解也會隨著時間而改變。人們會需要新功能；人們可能會發現某些規劃中的效能指標無法達成。稍後我們會提到規格文件應當如何修改，不過無論使用的媒介是什麼，在必要的時候每個人都應該知道怎麼修正、改良規格文件。

最後，你需要有能力證明你的系統行為符合規格文件的描述。這可以意味著測試，也可以意味著審查；基本上最重要的是，人們對於規格文件的每個部份都會有「感覺」，讓人們知道他們是否足夠精確。我會在後面補述這個部份。

簡單來說，能夠明確地回答，你以及你的團隊在打造的是什麼東西的精髓是：

1. 你應該將系統應有的行為寫下來
2. 它應該是一份有生命的文件，持續成長、更新。

• 它應該要盡可能完整（可以慢慢擴充而成）
• 它應該總是精確的

3. 每個人都應該知道怎麼找到這份文件、閱讀它、以及在文件中取得需要的答案。
4. 如果文件不完整或不精確，人們應該知道如何修改它。
5. 你應該要能夠證明你的系統真實行為符合它應該達成的行為。

能夠明確地回答，你以及你的團隊如何打造那個東西

正式來講，這包含的主題是系統開發計畫、驗證計畫、設計/程式標準、審核標準、以及文件管理。非正式來講，每個團隊成員都應該清晰無偏差地了解他們該怎麼做事。

而這...與流程大有關係。如何設計並驗證一個系統、如何捕捉需求、細至如何設定程式的格式標準；新手必須要精熟這一大堆事情才能夠在你的團隊中有效率地產出。

所以我再強調一次，如果資訊沒有被寫下來，那麼那些資訊就不存在。理想上，以下情境對於你的團隊來說應該是可達成的：某個新人報到的第一天，在他開始一切之前你們就都知道他（譯註：女性與其他跨性別者都是人，所以譯者繼續以他作為中性第三人稱應屬合理）需要哪些資源；你們能夠指引他去閱讀一份文件（這文件可以內建連結到其他必要的文件去）；該文件是可閱讀的；他接著就大致上能了解如何開始加入你的團隊協作。

你可以以任何方式去呈現這些資訊。Markdown 格式文件實務上運作良好。內部的維基系統也還可以。這些文件最後都會有點像是「流程的必要條件」。也就是說，

• 這些文件應該要是一份有生命的文件，持續成長、更新。
• 每個人都應該知道怎麼找到這份文件。
• 如果出現了任何歧見，「流程的必要條件」都應該有答案可以解決分歧；或者，就算沒辦法，你的團隊也應該能夠找出一個方法來決定如何將之寫下來到文件中。
• 不完整不是問題，總之持續改進就可以，但是...
• 不準確絕對是不能接受的。

沒有必要把所有流程都訂得非常嚴謹。大部分的團隊流程都不需要嚴格到符合安全需求標準。但如果有些事情必須天天做（像是合併請求的生成方式、審核程式碼、設計電路等等），也許把那些「流程指引」準備好，對於新人訓練會更有幫助。

如果團隊中有兩個人對於「如何完成 X 工作」有歧見，坐下來討論、做出決議、然後將之紀錄下來吧。然後就別再爭執該議題了，除非未來有個改動的好理由。

總之，有一份書面的流程指引能夠幫助你的團隊行動一致。一致性讓人們困惑該怎麼把事情做對的時間更短，也因此可以花更多時間在解決真正的問題上面。

TL;DR：總之，把東西寫下來。

在未來的某個時間點，我會寫一些你可能會想要引用作為「合理的預設工作模式」的做事情的方法。但說老實話，總之做些對你的團隊有用的事情，然後寫下他們，好讓每個人都能夠達成一致的理解。

總結

系統工程實踐在解決「解決問題」的問題上能夠派上用場。如果你有個大型團隊或是大型問題，「定義與解決某個問題」本身就是值得大家坐下來一起處理的問題。

如果狀況允許，在你開始工作之前花點時間確定每個人都已經準備好要解決同一個專案裡的問題，以及每個人都知道自己應當做些什麼。如果你已經開始了，這麼做也不會太遲，因為比起完全不做，你仍然可能提早抓到一些問題。

你不需要正規的訓練（譯註：但如果你需要幫助的話，可以寄一封信給作者），總之把東西寫下來，確保每個人都有一致的認知。

「在胡搞一通與科學之間唯一的差別是，有沒有把它寫下來。」
-- Adam Savage （流言終結者主持人）

譯者後記

如果資訊沒有被寫下來，那麼那些資訊就不存在

這個說法相當極端，且否定了部落知識與隱式知識的意義。實務上以譯者的經驗，組織內總是有些口耳相傳、僅有部份人最清楚的業務。雖不至於出現他們挾知識以自重的狀況，但沒有脆弱到可能會有單點故障的程度的話，（盡量）將所有知識建立一套流程文件的作法缺乏動機。

但反過來講，如果管理層願意推動這種實踐、這種文化，那麼執行面（可憐如你我般的基層主管）又要怎麼開始？不同組別亦敵亦友的同儕又該怎麼擺平呢？萬事起頭難，但會不會頭洗下去更有一堆沒想過的問題？可是如果一直做行前評估，會不會又像牧羊少年的奇幻旅程當中那一位一輩子都沒有起身朝聖的富有穆斯林一樣，天天看著麥加的方向，總覺得自己還沒準備好？

譯者目前也在技術組織之中面臨類似的管理問題，總覺得許多事情都不夠精確，但同時人們也欠缺動機去完成這樣一個體系。這的確需要文化、工具、慣例的形成，但這樣的協作模式不太可能自然湧現。譯者這次的翻譯只是撿現成的小小勞動，期望後續能夠換得一些 IT 領域前輩賜教的機會。

至少，丟出一些問題，試著讓答案慢慢成型。

感謝！