與我合作的接案開發者工作指南
過去七年來，我一直在聘請軟體開發者和其他接案工作者。雖然大部分的程式碼都是我自己寫的，但聘請其他開發者能帶來巨大的綜效，讓我能騰出時間處理事業的其他面向。
只要妥善經營合作關係，接案模式就能運作得很順利，但也有上百種可能出錯的方式。最好的起步方式，就是對接案者與客戶之間的關係建立共同的理解。
下面的文件說明了以接案開發者的身分與我合作會是什麼樣的情形。我會在發布的每一則開發職缺中都附上這份文件，並且在開始合作後，會付費請承攬人員仔細閱讀。它能吸引工作風格相近的應徵者，並縮短我聘請他們後的適應期。
我以 Creative Commons BY-4.0 license 授權公開這些指南，因此歡迎你重複使用或加以改作。
概述
這份文件說明了我與接案開發者合作時所採用的流程與慣例。
如果你是在與我合作前閱讀這份文件，可以先快速瀏覽，看看這樣的工作風格是否適合你。如果你是在合約執行期間閱讀，請仔細讀完，並將所花的時間列入請款。
黃金準則
我希望以我期待被對待的方式來對待你。
溝通
我最重視的就是有效的溝通。
寧可過度溝通，也不要溝通不足。在分享解決方案時，如果能說明你選擇它的原因，以及你曾探索過的其他途徑，會很有幫助。
快速處理電子郵件
我主要透過電子郵件溝通。
我的電子郵件風格是 Cal Newport（卡爾·紐波特）所說的 「process-centric（以流程為中心）」。簡言之，每封電子郵件通常代表一項任務或一個問題，我們的目標是用最少的來回往返來解決它。這需要我們雙方都用心撰寫郵件，而不是為了清空收件匣而匆忙丟出最快的回覆。
不佳的郵件往來範例
以下是一個虛構的不良郵件往來範例。接案者沒有在一開始就花時間思考自己需要的資訊，而是把問題一個一個擠出來問。
接案者：你偏好什麼圖片格式？PNG 還是 JPEG？
我：PNG
接案者：尺寸應該是多少？
我：800x600px
接案者：在較小的裝置上是否需要等比例縮放？
我：是的，在視口寬度小於 768px 時，尺寸應為 400x300px。
良好的郵件往來範例
相較之下，這個郵件往來範例回答了與上面相同的問題，但方式更有規劃、更有效率。
接案者：很希望能聽聽你對圖片的想法。可以告訴我你對以下幾點的偏好嗎？
- 格式（PNG 還是 JPEG）？
- 尺寸（以像素為單位）？
- 在較小的裝置上是否需要等比例縮放？
我：謝謝你提出這些經過深思熟慮的問題！
- 格式請用 PNG。
- 在視口寬度小於 768px 時，尺寸應為 400x300px。其餘情況下，尺寸應為 800x600px。
電子郵件回覆時間
我期待在一個工作天內回覆電子郵件。換句話說，如果我在週二下午 3 點寄信給你，我期待在週三下午 3 點前收到回覆。如果你還沒有完整的答案，請先回覆確認已收到訊息，並提供完整回覆的預計時間。
偶爾回覆時間超過一天是可以接受的，但應該是例外而非常態。你也可以對我有同樣的期待。
會議
會議適用於那些用文字溝通效率不彰或根本無法溝通的主題。會議的成本很高——它會打斷專注、限制行程安排，因此我會盡量減少會議。
我用電子郵件來傳達事實，用會議來互動討論主題。舉例來說，如果我們要審閱一份設計文件，不需要一起線上閱讀。相反地，我們可以事先各自閱讀文件，把會議時間保留給即時討論。
我也會每個月安排一到兩次會議，輕鬆聊聊、見個面。只靠電子郵件溝通，會讓人感覺 冷漠而緊繃。
| 討論主題 | 備註 |
|---|---|
| 「我們可以安排個會議來討論這個專案的截止期限嗎？」 | 不佳：這是個簡單的問題，不需要開會。 |
| 「我的下一個 pull request 你可能很難審閱。我們可以碰面讓我解釋給你聽嗎？」 | 不佳：如果程式碼複雜到難以理解，開會不是解決辦法。 |
| 「我對新架構有個想法。我們可以打個電話討論一下嗎？」 | 不佳：我會希望先從書面說明開始，等我看完後再討論。 |
| 「你的設計文件要求我們使用 Postgres，但我想了解限制條件，並討論其他選項。」 | 良好：這是個複雜的決定，可能需要許多細小的來回溝通，因此即時討論會比電子郵件更有效率。 |
| 「你在程式碼審查中給過我關於『cohesion（內聚性）』的回饋，但我覺得我們好像還沒有完全達成共識。我們可以碰面討論一下嗎？」 | 良好：如果我們已經嘗試用文字溝通某件事卻沒有效果，開會就是釐清問題的好方法。 |
面試
我從不透過正式面試來做聘用決定。
我會請你提供過往作品的範例，或透過電子郵件問幾個問題，但我最在意的是我們合作得好不好。如果你是合適的人選，我會以你平常的費率安排一個範圍明確的小型工作。一般人把這種模式稱為「contract-to-hire（先約聘後僱用）」。
如果我請你開始一項付費試做任務，即使我們之後決定不再合作，我仍會支付你的工時。唯一的例外是，如果你沒有盡力完成任務（例如，你為一項程式設計工作請款十小時，卻一行程式碼都沒交）。
盡職調查
當接案者能盡量減少我監督工作所需的時間時，就最能發揮價值。這需要在提問前先做好盡職調查。
你應該自在地尋求協助，但在可能的範圍內，我期待你能自行找到答案。如果你無法解決問題，請告訴我你已經嘗試過哪些方法。
不佳的問題
- 我該如何在我的電腦上安裝 Flask？
- 我該如何連結到 Google Doc 的特定段落？
- 數字 443 在我們的伺服器設定中有什麼意義？
良好的問題
- 我在理解規格第 3 節時遇到困難。「client」是指終端使用者，還是指 API 的客戶端？
- 當我嘗試安裝你的軟體時，出現了錯誤訊息
FooBarBaz。我已經重讀了安裝指南，也搜尋過未解決的問題，但還是找不出哪裡出錯。你知道問題可能是什麼嗎？
可配合時間
我不期待任何人每週工作超過五天。除非你另有告知，否則我會假定你週末不工作。
我週末和美國主要假日不工作。歡迎你在週末寄信給我，但我會等到下一個工作天才回覆。我盡量避免在美東時間中午以前寄送電子郵件。
你可以自由選擇工作時段，但我希望你的工時能與我的工作時間有部分重疊，我的工作時間是美東時間上午 10 點至下午 6 點半。
我不期待你每週都有固定的工作時程，但我越能預期你的工作時間，就越容易準備好能配合你時間的任務與回饋。
回饋
我在專案期間或結束後經常會主動徵求回饋。接案者對於改善流程或合作模式往往有寶貴的想法，但有時直到被直接詢問時，才會願意分享。
我通常會問：
- 有沒有什麼改變能讓工作更順暢或更愉快？
- 有沒有哪類型的工作你想多做一點？或少做一點？
截止期限
我很少需要急件，因此通常會讓你自行設定截止期限。你有責任在不需要我提醒的情況下如期完成。
不要讓截止期限悄悄過去卻沒有任何更新。如果你告訴我週二美東時間下午 3 點前會交件，到了週二晚上還沒有收到任何消息，會讓我感到焦慮。我會不禁猜想，你是不是完全忘了這項任務、得從頭開始，還是已經快完成了、幾個小時內就會交件。
如果你會無法趕上截止期限，請告訴我。越早警告我時程會延誤越好。最晚也應該在截止期限當下告知延遲。
一般來說，只要我能預先規劃，延遲並不是什麼大問題。如果某個截止期限對我很重要，我會事先告知。
在指定截止期限時，請使用精確、明確的時間表達方式：
- 還可以：我會在週五下班前寄給你
- 更好：我會在美東時間 12 月 8 日下午 5 點前寄給你。
- 不佳：我會在接下來幾天內準備好。
- 太模糊。
- 很差：好了我再通知你。
- 極度模糊
Timeboxing（時間盒）
在我們剛開始合作時，我會請你限制每週或每個里程碑的可計費時數。這麼做是為了在了解你的開發速度以及我們是否合作愉快之前，先控管請款金額。
如果你快達到上限卻還無法完成，請保留時間整理已完成的工作。透過電子郵件寄給我，並說明哪些已完成、哪些未完成，以及你預估剩餘工作還需要多少小時。
超過約定時數上限的時間，我將不予支付。
隨著我們合作越來越多，我會提高或取消時數上限，給你更多自主權。
文件
我非常重視文件。
如果專案有已文件化的流程或 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 專家，只要了解基本功能即可：
- 複製（clone）儲存庫
- 建立分支
- 建立提交
- 推送與拉取變更
- 變基（rebase）提交（偶爾需要）
GitHub 權限
我以 最小權限原則來分配存取權限。如果你是在我的公開儲存庫上工作，你可以直接 fork 並開始發送 pull request，無需額外權限。
我使用的兩個 GitHub 整合需要令人困擾的廣泛權限：CircleCI 和 Reviewable。這兩個應用程式都需要對你 GitHub 帳號中所有儲存庫的寫入權限。如果你對這些權限感到不安，你需要為與我合作的工作建立一個專用的 GitHub 使用者帳號，以便授予這些工具完整存取權。
提交整潔
有些開發者認為每一次提交都美好而神聖。我不是那樣想的。
對我來說，重要的是 main 分支要有合理的提交歷史。在其他所有分支上，你想怎麼提交都可以。你可以針對每則程式碼審查意見各做一次提交，也可以一次提交就處理所有意見。無論你偏好哪種工作流程，我都接受。我使用 GitHub 的 squash and merge（壓縮合併）功能，因此每個 pull request 最終都會被壓縮成單一提交。
如果你提交的 pull request 包含許多提交，我會閱讀 pull request 的標題、說明與留言。我不會逐一檢視個別的提交，因為我假定它們代表你的中間過程。文章 「How to Write a Git Commit Message（《如何撰寫 Git 提交訊息》）」描述了我偏好的貢獻紀錄風格，只是套用在 pull request 上，而非個別提交。
測試
當你建立 pull request 時，你有責任確保在 continuous integration(持續整合) 中所有測試皆通過。在送交程式碼給我審查前，請先修復任何建置失敗。
如果你新增了功能或以其他方式改變了行為，請更新自動化測試以涵蓋新行為。
如果你修改的功能難以用自動化測試，請手動測試該功能以驗證新程式碼。如果你找不到方法做到這點，請在送審時告知我這部分未經測試（這種情況應該極為罕見）。
可計費時數
我認為你為與我合作而做的幾乎所有事情，都屬於可計費的工作。
可計費工作的範例
- 與我溝通（包括電子郵件、視訊通話與面對面會議）
- 閱讀我請你閱讀的文件（包括這一份）
- 研究與工作相關的技術或科技
- 出去散步以思考複雜問題
不可計費工作的範例
- 把一整本書從頭到尾讀完，只因為它與你的工作相關
- 閱讀其中一個章節則是可以的。
- 因為硬碟壞掉而維修你的工作電腦
- 選購新的辦公椅
費用
我期待你自行提供作為接案開發者所需的基本工具（例如電腦、網路、電力）。
任何能讓你的工作更有效率或更舒適的軟體、服務或設備，我很樂意負擔費用。只需事先與我確認即可。
如果我請你購買與工作相關的物品，我會在你下一次請款時退還費用給你。
監控
我相信你會誠實回報工時。我絕不會要求你向我「證明」工時，或在你的系統上安裝任何監控軟體。
如果我們是在 Upwork 這類內建監控功能的平台上合作，我一定會將監控功能設為選用。除非工時出現嚴重落差，否則我不會查看監控資料。即使在那種情況下，我也會先與你溝通，才去檢視資料。
進度更新
要精確規定分享更新的頻率很困難，因為這需要一定程度的判斷。
對於範圍明確的任務，例如已充分理解的功能開發，請每累積八到十小時的可計費工時分享一次更新。對於範圍不固定的任務，例如錯誤調查或需要實驗的功能，請以每兩到四小時的可計費工時更新一次為目標。在沒有狀態更新的情況下，絕對上限應為三個曆日的可計費工作日或十小時的可計費時數，以先到者為準。
分享狀態更新的最佳方式，是透過能反映進度的 pull request。理想情況下，你可以將工作的一部分切出來，做成一個完整的 pull request；如果不行，也可以分享一個 pull request 並標示為「draft（草稿）」，表示仍在進行中。若要在調查錯誤時分享進度，請更新 GitHub issue，摘要你已調查的內容與所學到的資訊。
對於你不希望在 GitHub 上廣泛公開的工作相關後設討論，你可以私下寄信給我，但請盡量將討論保留在 GitHub 上。
付款
請每兩週寄送一次工時的請款單。請款後五個工作天內可望收到款項，通常會更快。
我不支付獎金或小費。我希望你的報酬是透明的，這樣你就不需要去猜測那些由我酌情決定的未定義報酬。
我會透過 PayPal、Payoneer、ACH 轉帳（僅限美國）或郵寄支票（僅限美國）付款，依你的偏好而定。
合約結束後的工作
我絕不會在工作結束後聯絡你，詢問與工作相關的問題或要求免費修改。在你合約期間內確認你已交付我要求的所有成果，是我的責任。
如果我在付款後才發現你作品中的問題，我有責任自行修復，或提供你額外的可計費時數來處理。
稅務
如果我在一個曆年內支付給你的金額超過 600 美元，我會需要一些稅務表格。
智慧財產權
如果我們合作的專案中我希望保留智慧財產權，我會寄送 一份合約給你進行電子簽署。其中聲明我將購買你為我撰寫的程式碼的著作權。
該合約僅針對我付費請你產出的工作，不包括你在為我工作的有償時數之外所創作的任何內容。
封面圖片由 Loraine Yow（蘿蘭·尤）創作。
你是客戶還是接案者？我很樂意看到類似的文件，或聽聽其他人如何處理這個問題，歡迎在留言區分享。