從初級開發到資深/首席開發，職業路徑通常很清晰：代碼寫得越好，能輔助高效編碼的技術、非技術能力越強，晉升速度就越快。但一旦到了資深級別，職業道路就會出現一個關鍵分叉。

很多開發者會選擇管理崗。這條路徑能大幅提升影響力，幫你在職業階梯上繼續攀升，但缺點也很明顯------你寫代碼的時間會越來越少，不少技術經理甚至完全沒時間碰代碼。如果你跟我一樣，這一點可能根本無法接受：以前你埋頭苦幹，把複雜流程轉化成優雅抽象的時間，會被會議、為團隊掃清障礙、調解分歧、應付 HR 流程考核這些事佔滿。這些工作雖有挑戰且重要，但和寫代碼完全是兩回事。

另一個常見選擇是架構師路徑。這條路上，你能始終深耕代碼，同時擴大自己的影響力，讓多年積累的經驗發揮更大價值。在很多公司，架構師路徑的薪資水平和職級晉升空間，與管理崗不相上下，而且兩條路徑最終都能通向高管崗位（比如 CTO）。

但相比管理崗，架構師路徑的定義似乎模糊得多。轉管理崗後，你的日常工作會徹底改變：日程表、團隊架構全變了，連工作成果的衡量標準都完全不同。可架構師的日常看起來和資深開發差別不大------在 IDE 裏寫代碼、審核 PR（代碼合併請求）、討論部署流水線和數據結構這些話題。那架構師到底特殊在哪？換句話説，要是你想證明自己能勝任架構師崗位，該怎麼做？

架構師到底是什麼？

架構師不只是"懂技術"或"腦子聰明"------這些特質只是幫你走到資深級別的基礎。也不只是"能設計並交付高可用、結構優良的系統"（雖然這也很重要）。

在我看來，核心差別就一個：

高級開發工程師懂得將代碼部署到由代碼構成的系統中，而架構師則懂得將想法部署到由人構成的系統裏。

這話聽起來可能像空洞的比喻，但我保證不是。

先説明白：我不是説架構師"擅長溝通"或"人緣好"（雖然這兩點確實有用），也不是用華麗辭藻強調"軟技能很重要"（雖然軟技能確實關鍵）。我想表達的是，架構師除了懂"部署機器和應用的流程"，更掌握一套高效、可複用的流程來組織和傳遞想法。他們清楚，單靠推送代碼能解決的問題有限；真正關鍵的問題，需要不同崗位、不同視角的人提供輸入、協作推進，最終達成共識才能解決。

換句話説，在大多數公司裏，想啓動一個持續數月的項目、重構某個 Web 服務，或是為新產品選定編程語言，都得獲得其他開發者和負責人的認可。軟件生命週期裏最大的瓶頸，從來都不是代碼本身------而是人的問題：溝通不暢、難以説服他人、決策卡殼。

所以，架構師要想產生影響力，就得一迭代接一迭代、一季度接一季度地推進這些事。怎麼才能穩定地讓"對的人在對的時間聚到一起，討論對的話題"？有沒有能對"人"生效的"傳輸協議"或"基礎設施即代碼"工具？

還真有。

而且不止一種：Confluence、飛書、語雀、Notion、......諸如此類。只要你會列點説明、能加文檔間的鏈接，就能"部署"自己的想法。在大多數公司裏，想做成一件事，最高效的方式就是：寫一份文檔，分享給關心這件事的人，然後傾聽他們的反饋。

但很多程序員對自己的寫作能力沒信心。要從自己熟稔的領域（編程，好壞自有代碼説話）切換到陌生的領域（寫作，好壞全看讀者判斷），確實不容易。所以下面我會給個"速成指南"：不用太多知識，就能幫你自信地寫出不錯（甚至優秀）的文檔，無論你之前會不會寫。你不需要有英語學位，不用認識"idempotent（冪等）"這種詞，甚至不用用母語寫------只要學幾個小技巧就行。

好文檔的核心原則

這是我對文檔寫作的"信條"：

我特意讓它和敏捷宣言的句式相近------右邊的做法有價值，但左邊的更關鍵。

後面我會詳細展開其中幾點，包括不同類型文檔該怎麼搭結構，但請記住第一點和第三點：與其卡在"找完美格式"上，不如先把你知道的寫下來；而且不同文檔的格式也不用統一，重點是"當下呈現這些信息，哪種方式最有效"，而不是"以前這麼做過"。

怎麼寫文檔？

哪怕你沒怎麼寫過技術文檔，也能寫出高質量的內容。有個簡單卻超好用的技巧，幾乎能讓你寫的任何文檔都變好用：用項目符號（bullet points）。

項目符號簡直是神器：它能讓你專注於信息的完整性和邏輯性，不用糾結句子通順與否、文采好不好。讀技術文檔的人，都想快速找到信息------其實衡量文檔好壞的最佳標準之一，就是讀者能多快找到所需信息並停止閲讀。如果 10 秒內找到答案就關掉，那這文檔就是成功的。而項目符號信息密度高、易瀏覽，剛好適配這個需求。

比如我剛才那兩段話，用項目符號寫是這樣的：

• 項目符號超適合技術寫作
• 幫你聚焦信息完整性和邏輯性
• 不用太多寫作技巧
• 讓文檔更易瀏覽

信息幾乎沒丟，但篇幅只佔原來的 25%，寫起來也更輕鬆。這就是為什麼項目符號是架構師的"最佳搭檔"。

第二個超有用的技巧是加標題（headers）。如果你的信息沒法用寥寥幾個項目符號説清，那就值得拆成幾個帶明確標題的小節。

比如我寫的大部分文檔，開頭都會有個"背景" section。作用是提供話題相關的歷史、業務領域或既定約束，順便加些鏈接。這些信息你天天接觸，可能爛熟於心，但其他讀者會需要"幫他們回憶"；就算是一年後你自己回頭看，也會感激當初寫的背景。

當然，對話題很熟悉的人，完全可以快速掃過甚至跳過"背景"部分------這就是標題的好處：能讓讀者更快找到自己要的信息，忽略無關內容。（如果標題太多，想優化體驗，加個帶鏈接的"目錄"也很好用。)

要是一開始不知道該加什麼標題，先隨便按順序列項目符號就行。之後把這些點按邏輯分組，再給每組貼個標籤------這和寫代碼其實很像：你可能先寫個 200 行的方法，跑通之後，通常會重構：拆成多個步驟，把重複邏輯抽成函數。

最要避免的是"大段密密麻麻的文字"。你文檔需要爭取注意力的人，往往都是時間最緊張的人。要是發過去一篇四頁紙的"小作文"，他們很可能根本沒時間讀。但如果是結構清晰的項目符號列表，他們就能快速滾動瀏覽，提取所需信息，有空再回復。

文檔寫完後該做什麼？

信息都寫好後，建議做個"合理性檢查"：發給你常合作的同事，讓他們指出不對勁或看不懂的地方。然後根據反饋修改、調整結構或重述內容。

要記住：大多數文檔更像"一次性的 Bash 腳本"，而不是"需要持續維護的 SaaS 應用"。一旦文檔完成了它的使命，你可能再也不會更新它。作為架構師，一年寫一百份文檔都很正常，根本沒時間全維護一遍。

這一點帶來兩個啓示：第一，要確保每份文檔"足夠好用"，哪怕以後逐漸過時，回頭看也能用上------現在多花點功夫，之後就能徹底忘了它，直到需要時再找。第二，要讓人能輕鬆看出文檔的"撰寫時間"，以及"同一時期還有哪些相關文檔"。只有明確知道"這文檔有多舊"，"特定時間點的記錄"才有價值。

我組織文檔的方式可能有點反直覺。大多數人會按"話題"分類：這個功能一個文件夾，那個功能一個文件夾。但這樣會導致一堆"看似平等、實則價值不一"的文件夾：有的裝滿最新、最相關的文檔，有的五年沒更新過，還有的新舊文檔混在一起，甚至互相矛盾，還看不出先後順序。

所以我幾乎所有文檔都按"時間"排序：先按年份，再按迭代週期（sprint）。這樣能清晰看到"時間線"。比如在 Confluence 裏，我會給每個團隊或產品建一個"空間"（其他工具可能叫"工作區""維基"或"文檔集"------高層次的分類還是需要的），但每個空間裏的文件夾結構是這樣的：

• 📄 概覽
• 📄 架構
• 📁 2025
• 📁 1 月第一迭代
• 📄 提案：SSO 登錄功能
• 📄 APP-132 用户會話研究
• 📁 1 月第三迭代
• 📄 APP-135 支持為指定客户配置 SSO 登錄
• 📁 2 月第一迭代
• 📄 SSO 登錄與用户角色的衝突問題
• 📄 開發預判：角色權限複雜度將上升

當然，少數"高層次文檔"確實需要持續維護。比如有人想了解產品概況，那有個最新的"首頁"和架構圖會很有用。但大多數文檔都有"有效期"：時間越久，相關性越低。

你可能會問："這不反常識嗎？我通常找的是'某個項目/功能的文檔'，不是'2020 年 3 月的文檔'啊。"我的回答是："不是有搜索框嗎？"按話題分類就像"給軟糖分類"------沒人能達成共識。這意味着你寫文檔時，要花時間想"該放哪個文件夾"；找文檔時，又要在錯的文件夾裏翻半天才能找到對的。這就像"按邏輯而非字母順序整理 CSS 屬性"：把 left 和 top 放一起可能感覺舒服，但沒實際用處。CSS 按字母排序更快、更簡單，還完全夠用；文檔按時間排序，道理也一樣。

而且説到底，"搜索"通常才是正確選擇。瀏覽適合用來"瞭解有哪些文檔"，但如果找特定信息，很容易漏掉那些標題看似無關、實則包含所需信息的文檔。而搜索又快，還能把所有匹配結果都列出來。按時間組織文檔，其實是"逼着"大家用搜索（本來就該這麼做）；而且點進搜索結果時，能立刻知道文檔的撰寫時間，以及當時還在推進哪些事------上下文一下子就全了。

文檔經過同行評審併發布後，最後一步是"複製鏈接分享出去"：如果這篇文檔替代或補充了其他文檔，就去那篇文檔里加個鏈接；如果和工單系統的任務相關，也貼過去；最後，把鏈接發給需要反饋、審批或共識的人。

附錄：高價值文檔類型

下面是幾種對技術團隊特別有用的文檔類型，供你參考。

1. 架構概覽文檔

• 用途：幫他人快速瞭解系統的結構和設計。
• 受眾：系統相關方，包括管理者、開發、運維、產品負責人等。
• 何時寫：搭建新系統或重構現有系統前；如果某個現有系統很難理解，也可以補一份。
• 內容：描述系統的核心組件（數據庫、應用、雲服務、負載均衡等）及組件間的交互方式；也可提及內部組件（如數據模型、類），但別寫太細。
• 結構：可以是"帶符號（圓柱代表數據庫、方框代表應用、箭頭代表交互）的 diagrams"，也可以是"分章節的多頁文檔"，甚至就是"嵌套的項目符號列表"。常見格式有 arc42 和 C4。
• 如何傳遞想法：哪怕是有點過時的架構概覽，也能幫參與者建立"系統的心智模型"，方便他們在此基礎上開發、排障和分析；同時也能讓負責人和運維理解"怎麼交付這個系統""成本多少""和現有系統怎麼交互"------這些都是系統能獲批的關鍵。
• 小貼士：記住"先記下來，別糾結結構"。不用非要按嚴格格式寫，也不用糾結符號對不對（除非你想）。"存在但不完美的架構文檔"，遠勝"完美但沒寫出來的文檔"。

2. 開發設計文檔

• 用途：針對"你想寫的代碼"收集反饋；提前發現潛在問題和複雜點，避免寫一堆半成品代碼最後還要刪掉。
• 受眾：團隊裏的其他開發者；未來想了解"系統演進過程"的開發者。
• 何時寫：開始任何"非 trivial（簡單）"的編碼任務前；如果某個本以為簡單的任務，越做越複雜，也可以補寫。
• 內容：細節程度自己定。不用寫 obvious（ obvious）的瑣事，但要包含"其他開發者能指出你假設錯誤""提醒你可用的現有邏輯/模式"的信息。
• 結構：列"要執行的步驟"即可。比如：給 A 類加一個實現 X 功能的方法、新建 B 類存儲 Y 相關數據、寫一個數據庫遷移腳本實現 Z 操作，等等。也可以加"待解決問題"部分（記錄開始前要明確的事），或"備選方案"部分（讓同事幫你權衡不同實現方式）。
• 如何傳遞想法：幫團隊分享知識，同時保留系統的核心模式和抽象；還能留下"系統為何變成現在這樣"的永久記錄。如果團隊不做結對編程/羣體編程，開發設計文檔能帶來類似的協作價值，還能幫未來的參與者快速熟悉系統。
• 小貼士：這話聽起來有點反常識，但確實是真的------寫的文檔越多，要寫的代碼越少。文檔能幫你避免"誤解、錯誤假設、設計缺陷"這些導致"PR 反覆修改""代碼重構"的問題；還能幫你省下"在探索性編碼上浪費的時間"（那些最後走不通的嘗試）。

3. 項目提案文檔

• 用途：説明項目的價值和成本，方便公司劃撥時間和資金。
• 受眾：負責人、產品負責人。
• 何時寫：規劃會議快開始時；或者你發現"能顯著改進公司產品/系統"的機會時。
• 內容：總結"負責人評估項目優先級時需要知道的所有信息"：為什麼重要？會影響誰？要做多久？等等。
• 結構：分幾個清晰的小節，比如"背景""待解決問題""建議方案""用户影響""預估開發工作量"。
• 如何傳遞想法：大型、有影響力、持續數月的項目，都是從項目提案開始的------它能為整個團隊設定路線圖。
• 小貼士：讓提案更容易獲得通過的關鍵，是"技術和非技術相關方都能看懂"。記住：別人不會像你一樣天天想這件事，所以"背景信息要比你以為的多"。提前做些調研：比如通過數據統計判斷會影響多少用户、問問大家"這個問題有多讓人頭疼"、看看其他團隊/公司是怎麼解決類似問題的。

4. 開發預判文檔

• 用途：指出"可能出現不如預期的結果"（尤其是隻有你憑藉經驗能預判到的風險），並提出應對建議。
• 受眾：業務決策的相關方。
• 何時寫：當某個決策讓你（作為工程師）覺得"有風險"或"可能會讓人失望"時。
• 內容：先總結"這個決策為什麼會被做出""決策者想達成什麼目標"；再説明"你覺得可能出問題的原因""具體會有哪些負面結果"；最後提出"緩解方案"，哪怕最終決策沒法改。
• 結構：結構清晰的文檔，分"決策內容""決策動機""潛在問題""可能結果""應對方案"等小節。
• 如何傳遞想法：幫你分享"專業預判能力"，讓大家提前關注計劃的漏洞；還能讓公司"在出問題時快速、靈活地應對"，而不是"反覆掩蓋問題"。如果計劃真的出了問題，你的預判文檔會變成"指路明燈"，清晰展示"預期和實際結果的差距"。
• 小貼士：保持中立語氣，別像個"唱衰的人"。多考慮幾種可能性，不用想着"扭轉整個決策"------只要指出風險，提出應對方法就行。

5. 技術選型文檔

• 用途：縮短"新建應用時的決策時間"。
• 受眾：開發團隊或整個技術部門。
• 何時寫：規劃項目時，團隊對技術選型有分歧。
• 內容：針對某類技術（編程語言、運行時、框架、平台等），聚焦"你和同事更傾向的幾個選項"，對比它們的優勢：公司對這個技術的熟悉度（不只是會用，還要包括部署和維護）？招懂這個技術且願意來的開發者容易嗎？開源生態活躍嗎？文檔全嗎？普通開發者從零基礎到做出可用應用要多久？它是否能促進"跨代碼庫通用的標準、結構和模式"？需要高性能時表現怎麼樣？把技術和非技術層面的優缺點説清楚後，給出"不同場景下的選型建議"：比如 Web 服務默認用 A，無服務器函數用 B，原型和內部應用用 C。
• 結構：先放"對比表格"，再分"不同場景的明確建議"。
• 如何傳遞想法：幫團隊就"技術實現方式"達成共識，讓開發者能快速搭建有用的技術方案，不用陷在"選 A 還是選 B"的爭論裏；還能挑戰"只靠傳統保留下來、而非因為適合或流行"的公司默認選型。
• 小貼士：別偏袒自己偏好的技術。如果你寫這份文檔，多找"用過不同技術的開發者"要反饋，把他們的意見和你的放在同等重要的位置。讓團隊達成共識，比"選絕對最好的技術"更重要。

6. 問題説明文檔

• 用途：快速就"問題的解決方案或規避方法"達成共識。
• 受眾：項目相關方。
• 何時寫：遇到"沒有明顯解決方案"的問題，需要公司明確決策時。
• 內容：用簡單的話説明問題是什麼；如果問題對業務有影響，描述（或預估）影響範圍和嚴重程度。大多數問題都涉及"兩個及以上無法同時滿足的約束條件"------如果是這樣，要明確寫出"這些約束是什麼""為什麼互相沖突"。然後給出"幾個可能的推進方向"，總結每個方向的優缺點。
• 結構：分"背景""問題描述""影響""約束條件""可能方案"等小節。
• 如何傳遞想法：一份好的問題説明文檔，能讓"無論什麼崗位的人"都看懂"問題是什麼、為什麼重要"，並對自己傾向的方案發表意見；還能留下"討論記錄"，方便後續參考------問題越大，越可能以後再被拿出來討論或復發。
• 小貼士：哪怕你想到的方案都不完美，也別跳過"可能方案"部分。任何工程師都能發現問題，但架構師的工作是找解決方案。就算只能想到幾個差方案，也能為別人提出好方案鋪路。

7. 事後覆盤文檔

• 用途：避免嚴重問題再次發生。
• 受眾：關心"近期故障、失敗或高優先級 bug"的人。
• 何時寫：技術問題造成較大影響時。大多數 bug 不用寫覆盤，但如果問題"嚴重影響業務正常運轉"（比如值班開發收到告警、用户打電話投訴），就該寫了。
• 內容：從"不追究責任"的角度，描述"問題是什麼""怎麼發現的"；附上相關的溝通記錄、PR 和工單號鏈接；説明"影響了誰""解決花了多久""期間做了哪些臨時緩解措施"；最後解釋"問題的根本原因"，並提出"避免再次發生的建議"。
• 結構：分"背景""問題描述""影響""時間線""根本原因""建議的流程改進措施"等小節。
• 如何傳遞想法：幫公司從"'這事絕不能再發生'的恐懼焦慮"，轉變為"'我們有辦法預防'的自信安心"；用得好的話，還能推動文化從"追究個人責任"，轉向"提升團隊能力和建立自動防護機制"。
• 小貼士：覆盤是"為錯誤承擔責任"的機會，但不是"自我指責"的儀式。每個人都有狀態不好、犯錯誤的時候。公司存在的意義，就是建立"超越個人能力的抗風險能力"。承認自己在其中的角色，但重點要放在"公司整體能改進什麼"上。