-- 背景 --

當你開始一家新公司并且必須非?？焖俚亟桓兑粋€MVP以評估市場適應性時，你可以原諒自己的粗心。在那個階段，目標是進行原始實驗，以便迅速評估你正在創(chuàng)建的產品的可行性，并快速進行變更。在這個階段，你通常是一個小團隊，每個人都彼此了解并始終保持溝通。

但隨著公司的發(fā)展，這種操作方式無法擴展，溝通變得越來越大的問題。以下是你可以使用的十個實踐，以顯著改善公司（或團隊）的溝通。

-- 原理 --

這些戒律的總體目標是最小化上下文切換的成本，以便你的工程師可以更快地進入流程。這也意味著更快地提供更好的軟件。

這些做法不僅有利于你的同事，而且在你回顧自己的舊工作時也有利于未來的你。

1.把同事當作客戶對待

你最重要的客戶是價值流中的下一步。如果你是一個與基礎設施工程師緊密合作的開發(fā)人員，請確保你的工作與基礎設施兼容（考慮12因素應用程序）。如果你是一名運維工程師，請確保開發(fā)人員可以自助獲取資源并部署應用程序。

確保你持續(xù)獲得同事的反饋，并根據需要調整以滿足他們的需求并減輕他們的工作負擔。

2.像準備要開源一樣創(chuàng)建代碼倉庫

我曾在許多地方工作過，那里的代碼倉庫非?；靵y，有多余的文件和代碼，沒有README文件，文件結構混亂，甚至還有密鑰。每當你創(chuàng)建一個倉庫時，請將其視為要開源，并考慮到那些不認識你或你的工作的人；他們如何知道這個倉庫是關于什么的？

3.追求編碼簡潔性

有些工程師編寫復雜的代碼，因為他們覺得自己顯得更聰明。我甚至遇到過一些認為代碼行數越多意味著工作產出越多的人。

絕對不，絕對不是這樣。編碼就像寫作一樣，當寫得清晰簡潔時，會更優(yōu)雅、更簡單、更容易理解。我理解想要寫更多代碼行的想法；如果經理只看到五行代碼，他們可能會覺得你懶惰。如果你在這樣的公司工作，我建議收拾行李換工作。你需要在一個鼓勵工程技藝的組織中工作；這對你的技能和心理健康最好。

編寫簡潔的代碼需要更多的時間和精力。它還與設計緊密相連；如果你在鍵盤上猛擊一堆代碼，你很可能對整個過程并不十分了解，并最終交付一份令人困惑的雜亂無章的文檔和自動化過程。

4.將Kondo原則應用于你的文件結構

Marie Kondo關于房屋整理的哲學很簡單：只保留那些“激發(fā)喜悅”的東西，讓一切整潔有序。

文件可能沒有物品那么令人愉悅，但是你不應該保留任何不起作用的東西。工程師在代碼倉庫里摸索、嘗試解決問題的各種不同方法，然后在成功后留下所有東西，這種情況太常見了。這種混亂使得后來找到該倉庫并嘗試理解其目的的人非常困惑。對于下一個需要清理你的混亂的人來說，這也更具挑戰(zhàn)性，因為他們需要知道如何刪除而不改變你的代碼的功能。請記住，你可以在git中恢復刪除的所有內容，所以在清理時要毫不留情！

文件結構同樣至關重要。我曾與許多人合作，他們創(chuàng)建代碼倉庫的文件結構就像我母親整理她的廚房一樣——她知道每樣東西都放在哪里，但其他人卻不知道！一個有組織的文件結構和合適的目錄名稱使理解變得更容易。為需要解釋的任何目錄添加README.md文件。

5.了解你正在做的事情

這一點似乎很明顯，但你不知道我遇到了多少次顯而易見的是工程師不知道自己在做什么的代碼。

我遇到的最惡劣的例子是開發(fā)人員編輯NGINX和Apache配置文件，試圖解決他們的Java代碼中的問題，而這些問題本應該在代碼中解決。他們從StackOverflow粘貼配置行，看看是否有效；有時有效，有時沒有任何作用，但他們總是把所有內容留在文件中。結果是，我繼承了龐大的配置文件，沒有人能理解，也沒有人敢編輯，擔心會破壞某些功能。

不要盲目地復制粘貼StackOverflow上的代碼。嘗試理解你粘貼的代碼，并附上來源和解釋的評論。ChatGPT和其他AI工具會使這個問題變得更糟；如果你使用這樣的工具，試著讓AI先解釋一下，并添加相關的注釋！

6.根據上下文進行文檔記錄，而不是全面記錄

當敏捷宣言說“優(yōu)先考慮有用的軟件，而非詳盡的文檔”時，他們并不是說完全不需要文檔。但這并不意味著你需要過度記錄所有東西。

上下文文檔旨在為了解、操作和診斷應用程序的人提供所需的所有信息。為什么、什么時候、誰、什么和怎么做；先決條件、示例、如何測試應用程序——任何你需要開始的東西。

想象一下，我給你一個包含50種不同類型的草藥和廚房食材描述的清單——這就是詳盡的文檔?，F在想象一下，我讓你用這些東西做飯。如果沒有任何先前的知識，你能做到嗎？可能不能，但這就是大部分軟件文檔的現狀（想想man頁）。

相反，如果我給你一些解釋如何使用這些草藥的食譜會更有幫助——這就是上下文文檔。提供上下文文檔對用戶更有價值，而且可能花費更少的時間。

如果你的上下文文檔臃腫且難以理解，問問自己以下問題，我是否可以通過設計我的工作來減輕這種情況？答案通常是肯定的，因為令人困惑和過多的文檔通常掩蓋了糟糕的設計。

始終詢問同事和其他團隊你的文檔是否合理，并在需要時改進。目標是他們不需要向你提問，他們可以自己有效地解決問題。

7.將文檔與源代碼保持緊密聯(lián)系

如果索倫在指環(huán)上附上了一個很好的README.md文件，甘道夫可能會更早地了解到指環(huán)。

許多公司有一個趨勢，所有文檔都放在Confluence中；這是一個好做法。然而，這通常意味著將文檔與代碼庫分開。我認為這種做法存在兩個問題：

1. 你需要維護兩個真實來源。
2. 你必須相信你的客戶知道這個Confluence頁面在哪里，以及她是否有權限訪問。

讓所有內容都集中在一個地方，可以讓你和你的客戶更簡單。我建議在Confluence中引用代碼庫，添加對其功能的描述，并提供指向README.md的鏈接以獲取更多文檔。

在wiki中維護適用于多個代碼庫的通用文檔或具有復雜格式的教程，同時在需要時提供指向代碼庫中README.md文件的鏈接。這樣，更新README.md文件的詳細信息會更容易。

或者，你可以使用任何簡化此過程的工具，讓文檔方便使用且集中存放，同時只需編輯一次。最重要的是，查看你的代碼的人應該知道文檔在哪里并能夠訪問它。

8.為同事編寫有意義的工單

當你編寫工單時，請?zhí)峁┖啙嵜髁说募毠?jié)。我經?？吹竭@樣的糟糕工單：

一句話、含糊不清的工單：比如“為x創(chuàng)建角色”或“為y提供根權限”并不是好的工單。

雜亂無章、冗余信息過多的工單：一個常見的例子是粘貼一系列電子郵件，這樣需要完成工作的人必須閱讀整個交流過程并試圖理解其中的意義。這樣做浪費了需要完成工作的人大量時間去建立上下文。

相反，你可以使用這樣的結構：

• 描述：包括上下文和原因。
• 驗收標準：包括驗收人。
• 有用的來源：指向可能有助于完成任務的資源的鏈接。
• 工作位置：指派人在需要時可以填寫。

對于更新和障礙，請使用工單的評論。如果需要，每天都可以這樣做。

這樣編寫工單非常有助于了解你的看板以及每個人正在從事的工作。這也使得查看工作流程和常見障礙更容易，避免了每天站立會議上信息未被記錄且流程被中斷的情況。

9.共享工程和溝通原則

僅憑你自己產出優(yōu)秀的工作是不夠的，如果你必須不斷地修復他人的工作或試圖理解他們的混亂，有時候最好退一步，與團隊成員或其他與代碼有關的團隊進行討論，并盡早解決這些問題。

明確并有效地定義什么是優(yōu)秀的工作以及如何實現它，制定一些指導方針并與你的團隊和整個公司分享——最重要的是，承諾遵循這些指導方針！

10.將大部分努力用于創(chuàng)新和優(yōu)雅的設計

確?；〞r間做好工作；如果產品負責人或其他人試圖推動你更快地交付，請尋求折衷，并解釋現在節(jié)省時間，將來會花費更多時間和金錢。敏捷并不意味著高速開發(fā)；它意味著快速、短小的高質量軟件迭代，遵循節(jié)省時間的設計原則。

-- 總結 --

最近，我對平臺工程和內部開發(fā)者平臺的實施變得非常熱衷，因為通過將工作哲學轉向自助服務和開發(fā)者體驗（DX），上述所有原則都成為開發(fā)的基本目標。然而，了解良好溝通的原則以及如何實施它們是了解為什么它們可以長期節(jié)省時間和精力的基本要求。

-- 補充 --

以下五點補充建議將有助于提高團隊在工程交流方面的效率和協(xié)作，從而提高項目的成功率。

11.定期進行代碼審查和團隊討論

通過定期進行代碼審查和團隊討論，可以確保團隊成員共享知識、了解彼此的工作以及相互學習。這有助于減少誤解，并在項目中建立統(tǒng)一的編碼和文檔風格。

12.使用可視化工具來解釋復雜概念

利用流程圖、架構圖和其他可視化工具來解釋復雜的系統(tǒng)和概念。這將有助于提高團隊對項目的理解，并使概念更容易傳達給新成員或其他團隊。

13.提倡開放式溝通和反饋文化

鼓勵團隊成員在遇到問題或不清楚某些事物時，主動尋求幫助和建議。通過建立一種積極的反饋文化，可以確保問題得到解決，并鼓勵團隊成員互相學習。

14.定期進行知識分享會

組織定期的知識分享會，讓團隊成員分享他們在項目中學到的新知識、技術和最佳實踐。這不僅可以提高團隊的技能水平，還有助于建立團隊凝聚力。

15.利用協(xié)作工具進行有效溝通

使用協(xié)作工具，如Slack、Microsoft Teams或其他即時通訊工具，以便團隊成員可以輕松地共享信息、討論問題并協(xié)作解決問題。同時，利用項目管理工具（如Jira或Trello）跟蹤任務和進度，確保團隊工作得當且透明。