與我合作的接案開發者指南
原文由 Michael Lynch 于 發布，訂閱此部落格
過去七年來，我一直在聘用軟體開發者和其他接案工作者。雖然大部分程式碼都是我自己寫的，但聘用其他開發者能帶來極大的加乘效果，讓我有時間處理事業的其他面向。
如果能妥善經營合作關係，與接案者合作的效果會很好，但也有上百種可能出錯的方式。最好的起步方式，就是雙方對接案者與客戶的關係先達成共識。
下面的文件說明了以接案開發者的身分與我合作是什麼樣的體驗。我會把它附在每一個我發布的開發職缺公告中，開始合作後也會付費請承包人員仔細閱讀。它能吸引工作風格相近的人選，也能縮短聘用後的適應期。
我以創用 CC 姓名標示 4.0 授權公開這份指南，歡迎你自由重複使用或改作。
概覽
這份文件說明了我與接案開發者合作時所採用的流程與慣例。
如果你是在與我合作前閱讀這份文件，可以先快速瀏覽，看看這樣的工作風格是否適合你。如果你是在合約進行期間閱讀，請仔細讀完，並將閱讀時間計費給我。
黃金準則
我希望以我期待被對待的方式來對待你。
溝通
我最重視有效溝通。
寧可過度溝通，也不要溝通不足。分享解決方案時，如果能說明你為何選擇這個方案、以及考慮過哪些其他做法，會很有幫助。
快速解決 Email 往來
我主要透過 Email 溝通。
我的 Email 風格是 Cal Newport 所說的「以流程為中心」。簡單來說，每封 Email 通常代表一項任務或一個問題，我們的目標是用最少的往返次數解決它。這需要我們雙方都用心撰寫郵件，而不是為了清空收件匣就匆匆丟出最快的回覆。
不良的 Email 範例
以下是一個虛構的不良 Email 往來範例。接案者沒有一開始就花時間思考自己需要的資訊，而是一個一個零散地拋出問題。
接案者：你偏好哪種圖片格式？PNG 還是 JPEG？
我：PNG
接案者：尺寸應該是多少？
我：800x600px
接案者：在較小的裝置上需要縮放嗎？
我：需要，在視窗寬度小於 768px 時應顯示為 400x300px。
良好的 Email 範例
相對地，這個 Email 往來回答了與上面相同的問題，但方式更有規劃、更有效率。
接案者：想請教你對圖片的偏好，可以告訴我以下幾點嗎？
- 格式（PNG 還是 JPEG）？
- 尺寸（以像素為單位）？
- 在較小的裝置上是否需要縮放？
我：謝謝你這些考慮周到的問題！
- 格式請用 PNG。
- 在視窗寬度小於 768px 時，尺寸應為 400x300px。其他情況下則為 800x600px。
Email 回覆時間
我期待在一個工作天內回覆 Email。換句話說，如果我在週二下午 3 點寄信給你，我期待在週三下午 3 點前收到回覆。如果你還沒有完整的答案，也請先回覆確認已收到訊息，並提供完整回覆的預計時間。
偶爾回覆時間超過一天是可以接受的，但應該是例外而非常態。你也可以對我有同樣的期待。
會議
會議適用於那些用文字溝通效率不彰或根本無法溝通的主題。會議的成本很高——會打斷專注、限制行程安排，所以我會盡量減少會議。
我用 Email 傳達事實，用會議來互動討論。例如，如果我們要審閱一份設計文件，不需要在會議中一起閱讀。我們可以事先各自讀完，把會議時間留給即時討論。
我也會每個月安排一到兩次會議，輕鬆見個面聊聊。只靠 Email 溝通有時會讓人覺得顯得冷漠又緊繃。
| 討論主題 | 備註 |
|---|---|
| 「我們可以安排個會議來討論這個專案的期限嗎？」 | 不佳：這是個簡單的問題，不需要開會。 |
| 「我的下一個 pull request 你可能很難審查。我們可以見面讓我解釋一下嗎？」 | 不佳：如果程式碼複雜到難以理解，開會並不是解答。 |
| 「我對新架構有個想法。我們可以打個電話討論一下嗎？」 | 不佳：我比較希望先從書面說明開始，等我讀過後再討論。 |
| 「你的設計文件要求我們使用 Postgres，但我想更了解限制條件，並討論其他選項。」 | 良好：這是個複雜的決定，可能需要多次來回討論，因此即時討論會比 Email 更有效率。 |
| 「你在程式碼審查中給了我關於『內聚度』的回饋，但我覺得我們似乎還沒完全達成共識。我們可以約個時間聊聊嗎？」 | 良好：如果我們已經嘗試用文字溝通卻行不通，開會就是把問題釐清的好方法。 |
面試
我從不透過正式面試來做聘用決定。
我可能會請你提供過往作品範例，或透過 Email 問幾個問題，但我最在意的是我們合作起來是否順暢。如果你是合適的人選，我會以你平常的費率安排一個範圍明確的小型試作任務。一般人會把這種模式稱為「先約聘、再聘用」。
如果我請你開始進行有給的試作任務，即使事後我們決定不再合作，我仍會支付你的工時。唯一的例外是如果你沒有盡力完成任務（例如，你在一個程式任務上請款十小時，卻一行程式碼都沒交）。
事前準備
接案者最能發揮價值的時候，就是盡量減少我需要監督的時間。這需要在提問前先做好功課。
你應該自在地尋求協助，但在可能的範圍內，我期待你先自行尋找答案。如果真的無法解決，請告訴我你已經嘗試過哪些方法。
不佳的提問
- 要怎麼在我的電腦上安裝 Flask？
- 要怎麼連結到 Google 文件的特定段落？
- 在我們的伺服器設定中，數字 443 有什麼意義？
良好的提問
- 我對規格書第 3 節有點不太理解。「client」指的是終端使用者，還是 API 的客戶端？
- 我嘗試安裝你的軟體時，出現了
FooBarBaz的錯誤訊息。我已經重讀了安裝指南，也搜尋過現有的 issue，但還是找不出問題所在。你知道可能是什麼原因嗎？
工作時間
我不期待任何人一週工作超過五天。除非你另有告知，否則我會假設你週末不工作。
我週末和美國主要假日不工作。你當然可以在週末寄 Email 給我，但我會等到下一個工作天才回覆。我也盡量避免在美東時間中午之前寄信。
你可以自由安排工作時段，但我希望你的工時能與我的工時有一部分重疊，我的工作時間是美東時間上午 10 點到下午 6 點半。
我不期待你每週都有固定的工時，但我越能預測你的可工作時間，就越容易配合你的時間來準備任務和回饋。
回饋
我在專案進行中或結束後經常會主動徵詢回饋。接案者往往對改善流程或合作方式有寶貴的想法，只是有時在被直接詢問之前，不太敢主動提出。
我通常會問：
- 有沒有什麼改變能讓工作更順暢或更愉快？
- 有沒有哪類型的工作你想多做一點？或少做一點？
期限
我很少需要趕工，所以通常會讓你自行設定期限。你有責任在不需要我提醒的情況下準時完成。
不要讓期限到了卻毫無消息。如果你告訴我週二美東時間下午 3 點前會交件，結果到週二晚上都沒收到任何消息，我會很焦慮。我會不確定你是完全忘了這件事、得從頭開始，還是已經快完成了、幾個小時後就會交件。
如果會趕不上期限，請告訴我。越早警告我時程會延誤越好。最晚也一定要在期限當下告知延遲。
一般來說，只要我能及早規劃因應，延遲並不是什麼大問題。如果某個期限對我很重要，我會事先告訴你。
設定期限時，請使用精確、明確的時間表述：
- 還可以：我會在週五下班前寄給你
- 更好：我會在美東時間 12 月 8 日下午 5 點前寄給你。
- 不佳：我這幾天內會準備好。
- 太含糊。
- 糟糕：好了再跟你說。
- 極度含糊
工時上限
在我們合作初期，我會請你限制每週或每個里程碑的計費時數。這是為了在我了解你的開發速度、以及我們是否合作愉快之前，先控管費用。
如果你快達到上限卻還無法完成，請留一些時間整理已完成的工作。用 Email 寄給我，說明已完成的部分、未完成的部分，以及你預估完成剩餘工作還需要多少時數。
超過約定時數上限的工時，我不予支付。
隨著我們合作越來越久，我會逐步放寬或取消時數上限，給你更多自主空間。
文件
我非常重視文件。
如果專案有既定的流程文件或 GitHub 範本，請遵循它們。如果文件指示你做的事情看起來不太對，請告訴我。不要自行假設說明已經過時或不適用於你。
當你開始與我合作某個專案，你就成了該專案入門文件的最新擁有者。如果你因為文件寫得不好或根本沒寫而卡關，請幫忙提交修改來補齊缺口。
請用心為你撰寫的程式碼加上文件。盡量讓程式碼本身就能自我說明，但對於程式碼無法表達的資訊，請加上註解。為新程式碼加上註解時，詳細程度請大致與周圍的程式碼保持一致。
# Number of days per week (seven) <-- BAD comment
DAYS_PER_WEEK = 7
# This is a workaround for a bug in FooComponent, which crashes the process
# if we call it immediately after writing to disk. <-- GOOD comment
time.sleep(5)
程式碼品質
我重視品質與可維護性更勝於交付速度。
當你已經有能運作的程式碼時，請尋找簡化或重構邏輯、讓它更直觀的機會。如果多花一倍的時間能讓程式碼簡單 30%，對我來說就是划算的。
程式碼審查
我會徹底審查所有的程式碼變更，並提供詳細的回饋。
我的意見並非要批評你或讓你難受。我嚴格審查是為了理解程式碼，並讓它達到我能長期維護的水準。
以下文章說明了我的程式碼審查流程：
程式碼風格
我的專案遵循 Google 的程式碼風格指南：
在可行的範圍內，我會使用自動化工具來落實風格規範。
Git
我使用 Git 進行版本控管。你不需要是 Git 專家，只要了解基本操作即可：
- 複製儲存庫
- 建立分支
- 提交變更
- 推送與拉取變更
- 變基提交（偶爾需要）
GitHub 權限
我以最小權限原則分配存取權限。如果你在我的公開儲存庫上工作，你可以直接 fork 後開始發 pull request，不需要額外權限。
我使用的兩項 GitHub 整合服務需要範圍令人困擾的廣泛權限：CircleCI 和 Reviewable。這兩個應用程式都要求對你 GitHub 帳號中所有儲存庫的寫入權限。如果你對這些權限感到不安，你需要為與我合作的工作另外建立一個專用的 GitHub 帳號，以便授予這些工具完整存取權。
Commit 習慣
有些開發者認為每一次 commit 都是美好而神聖的。我不是那樣想的人。
對我來說，重要的是 main 分支要有合理、清晰的 commit 歷史。在其他分支上，你想怎麼 commit 都可以。你可以針對每一則程式碼審查意見各做一個 commit，也可以一次解決所有意見後只做一個 commit。無論你偏好哪種工作流程我都接受。我使用 GitHub 的 squash and merge 功能，所以每個 pull request 最終都會被壓成單一 commit。
如果你提交的 pull request 包含許多 commits，我會閱讀 pull request 的標題、說明和留言。我不會逐一檢視個別的 commit，因為我假設那只是你的中間過程。文章〈如何撰寫 Git Commit 訊息〉描述了我偏好的貢獻紀錄風格，只是套用在 pull request 上，而非個別 commit。
測試
當你建立 pull request 時，你有責任確保所有測試在持續整合中都能通過。在送審程式碼之前，請先修復任何建置失敗的問題。
如果你新增了功能或以其他方式改變了行為，請更新自動化測試來涵蓋新的行為。
如果你修改的功能難以用自動化測試，請手動測試該功能以驗證新程式碼。如果你找不到方法這麼做，請在送審時提醒我這部分尚未測試（這種情況應該極為罕見）。
計費時數
我認為你為與我合作所做的幾乎所有事情，都屬於可計費的工作。
可計費工作的範例
- 與我溝通（包含 Email、視訊通話和面對面會議）
- 閱讀我請你閱讀的文件（包含這一份）
- 研究與工作相關的技術或科技
- 出門散步思考複雜問題
不可計費工作的範例
- 把一整本書從頭到尾讀完，只因為它與工作相關
- 讀一個章節是可以的。
- 因為硬碟壞掉而維修你的工作電腦
- 挑選新的辦公椅
費用
我期待你自行提供身為接案開發者所需的基本工具（例如電腦、網路、電力）。
任何能讓你的工作更有效率或更愉快的軟體、服務或設備，我很樂意支付費用。只要事先跟我說一聲就好。
如果是我請你購買與工作相關的物品，我會在你下一次請款時退還費用。
監控
我相信你會誠實回報工時。我絕不會要求你「證明」工時，或在你的系統上安裝任何監控軟體。
如果我們是透過 Upwork 這類內建監控功能的平台合作，我一律會將監控功能設為選用。除非工時出現嚴重的落差，否則我不會檢視監控資料。即使真的發生這種情況，我也會先與你溝通後才去查看資料。
進度更新
很難精確規定多久要分享一次進度，因為這需要一定程度的判斷。
對於範圍明確的任務，例如已經充分理解的功能開發，請每累積八到十小時的計費工時分享一次進度。對於範圍不確定的任務，例如除錯調查或需要嘗試摸索的功能，請每兩到四小時的計費工時就更新一次。最長不更新狀態的時間上限，是三個有計費的日曆天或十小時的計費工時，以先到者為準。
分享進度的最佳方式，是透過能反映進展的 pull request。理想上，你可以擷取工作中已完成的部分組成一個完整的 pull request；如果不行，也可以分享一個 pull request 並標示為「draft」，表示仍在進行中。若是在進行除錯調查時要分享進度，請在 GitHub issue 中更新你已調查的內容與發現。
如果你想私下討論不想公開在 GitHub 上的工作相關事務，可以用 Email 私下寄給我，但請盡量將討論留在 GitHub 上。
付款
請每兩週寄一次工時請款單。請款後五個工作天內會付款，通常會更快。
我不支付獎金或小費。我希望你的報酬是透明的，讓你不必揣測那些由我自由裁量的不確定收入。
我會透過 PayPal、Payoneer、ACH 轉帳（僅限美國）或郵寄支票（僅限美國）付款，依你的偏好而定。
合約結束後的工作
我絕不會在工作結束後還聯絡你詢問工作內容，或要求免費修改。在你合約期間內確認你已交付我要求的所有成果，是我的責任。
如果我在付款後才發現你工作中的問題，我會自行負責修復，或提供額外的計費時數請你處理。
稅務
如果我在一個日曆年度內支付給你的金額超過 $600，我會需要一些稅務相關表格。
智慧財產權
如果我們合作的專案需要我保留智慧財產權，我會寄給你一份合約進行線上簽署。合約中會載明我購買你為我撰寫的程式碼之著作權。
該合約僅針對我付費請你產出的工作，不包含你在有給工時之外自行創作的任何內容。
封面插圖由 Loraine Yow 繪製。
你是客戶還是接案者呢？我很想看看類似的文件，或聽聽其他人如何處理這個問題，歡迎在留言區分享。
留言
登入後參與討論