GitHub 協作五大業餘姿勢

近期看到不少同伴使用 GitHub 協作，我開始理解當初 @ZoomQuiet 大媽和我協作時的痛苦感受 —— 這不順眼那不專業，比如用中文命名、創建 wiki 卻不更新 sidebar、滿屏 Issue 不及時 close、Issue 通篇沒有一個超鏈接等，雖不至釀成大錯，但實在讓人渾身不自在。遂復盤自己踩坑經歷，供你規避幾大常見業餘姿勢，少走彎路，更快體會 GitHub 協作的舒爽樂趣。

注意：

若不了解 GitHub 是什麼，請先移步 GitHub 基礎教程：

GitHub Guides：https://guides.github.com/

GitHub Training & Guides - YouTube：https://www.youtube.com/githubguides

本文所列建議主要針對非技術協作的知識管理型團隊，如果你對所在團隊是否是知識管理型團隊無所謂，這篇文章不必往下看了;-)

嗯哼，如果以上兩坎你都越過，那來看看我被咆哮嫌棄 N 次的業餘姿勢你中了幾個吧……

用中文命名 wiki 或文件

初次創建 wiki ，我以中文命名，被大媽在協作群里如是咆哮，記憶深刻。

由於更熟悉漢語，或不知道該以什麼英文命名，不少人和我當初一樣，下意識用中文命名文檔。這是新手最常出現的姿勢，尤其沒有技術背景的新手。

那在 GitHub 用中文命名文件，有何不妥？

對比一下由此生成的 wiki pages URL 就知道了

wiki title 為 「Test」 的頁面：

wiki title 為 「測試」 的頁面：

你覺得哪個 URL 更乾淨易懂簡明專業？

再看一下目錄，用中文真是不忍直視……

總之，若你不想徒增煩惱，也不想被隊友嫌棄，在 GitHub 命名中請別出現中文。

不僅 GitHub ，在其它團隊系統中，也都建議你用非中文。畢竟中文同一個意思可以有多種表達，而各人用詞、命名習慣不一樣，難以形成共識，真是團隊知識管理的一大災難。比如這個：

在某以中文為主的協作界面檢索「品牌」後返回的結果

檢索「品牌」一詞返回這麼多結果，每次我都要點擊不下 6 次，翻來覆去對比確認哪個是最新的、可用的文檔。若用 wiki 來管理文檔，且用英文命名，就不必如此煩惱啦，比如在集團倉庫下：

BrandAnrenInfo

BrandOMCInfo

BrandOMCRule

BrandiBrainRule

每次直接在唯一指定文檔上更新，同事也直接從唯一指定文檔取用信息，豈不快哉？

當然，這需要團隊有統一的文件命名規約、同事也都熟悉並遵守。否則，別掙扎了，要找東西就繼續在群里吼誰有/誰知道在哪兒吧……

wiki pages 從不掛 sidebar 也不和 Issues 關聯

如果沒有任何鏈接,這是個 孤懸文章, 慘烈地被人遺忘是必然的,,,,

看到我們在 GitHub 創建孤懸文檔，大媽幽幽吐出無奈和嫌棄。

估計是使用網盤的慣性，很多夥伴創建完 GitHub wiki pages ，就了沒下文。頂多發給正在協作的人，就再沒然後。你認為這種習慣，將如何影響團隊知識管理和經驗傳承？

是不是沒有一個公共的頁面知道目前團隊里都有哪些資料/資源？

尤其當 wiki 中的文檔越來越多卻沒有直觀的索引時，團隊成員是不是更不樂意整理和復用？

且更新 wiki，一般不會有自動提醒（包括郵件和關聯的 slack 等信息集成服務），除非在個人消息中查看。但一般少有人從那裡查看吧？消息實在太多……

所以，團隊中知識管理素養良好的成員，一般會用類似 GitBook 的內在順序在 wiki 中創建 page：

先在 Home/_sidebar.md 中設計一個合理的鏈接點

給出文檔標題和 wiki 文件名

然後在合理的目錄下創建 對應 文件名的 .md

再開始編輯 文件內容

並在提交前先 pull 倉庫的變化，完成衝突解決後 push

完成以上動作後，關聯驅動這個 wiki 完成的 Issue：

除了放在 sidebar 中、和 Issue 關聯，還和配套使用的文檔關聯以便取用

這就完了嗎？當然不！還需在協作界面知曉相關人員，比如在 IM 群或任務看板中拋出鏈接（注意運用 GitHub 錨點特性）並艾特相關夥伴，請其查看後進入下一環：

通知對方看某個 wiki

通知對方看某個 Issue 的某個 comment

通知對方看自己修訂了哪些內容

通知對方看自己新增了哪些內容，內容不止一條時可用 commit 錨點快速定位

寫文案真的只有「文案」

A：小王，你知道這些產品介紹是用於什麼場合的嗎？哪些是給用戶直接看的，哪些給我們的合作夥伴看，哪些是給同事們看後給用戶、合作夥伴介紹產品的？

B：我看看……呃，我也分不清楚……也沒註明是誰編製的，想直接找他問都難！

A：……

類似的情景你是否常碰到？你在公共界面發現某個文檔，卻無從判斷是否可用，用在何種場合，只能花時間自己梳理。就算找到創建人，溝通確認要花雙方几分鐘吧？要是你用每個文檔都要問創建人，每個用文檔的人都問創建人，經年累月，OMG ，這對團隊來說是多可怕的成本，浪費了多少青春！

如何避免？珍惜生命，從我做起。

在公共目錄創建文檔，請在開頭加上頭部說明，以 5W1H 簡要說明文檔背景、使用情境（比如官網/微信/郵件/宣傳冊etc.）等信息，以便同伴快速理解調用。比如：

標題比正文更重要，別漏了！

更多創建文檔的建議，可以參考這個 協作文檔撰寫指南：

https://github.com/OpenMindClub/Share/wiki/HbDoc

多寫幾行字你嫌麻煩？

那是你沒考慮時間的複利效應啊——

對，在私人目錄建個文案自己看，自己記得創建了什麼/用於什麼場合/怎麼命名，需要的時候及時找到就好。

但在團隊界面，你創建的東西，通常還需同伴 知曉/修訂/審核/使用，而且涉及不止一位夥伴。考慮人數和時間的幾何疊加，嘖嘖，這省下來的成本，值得叫老闆給你加薪~

Issue 當 BBS 來用

線上溝通，你是否也有類似感受——

延續 QQ、Wechat 等平台的 IM 慣性，越來越習慣撕扯跳躍的碎片交談；貼吧/BBS/V2EX 樣的壘樓，誘你快速回復，而不是逐一回復觀點；線上交流，沒人對某個話題負責，聊到哪兒算哪兒，無所謂有無共識/結論，也不管一頭扎進來的人作何感受？

嗯，當下生活的確這樣。

但！團隊協作，是為推進行動、創造價值，不是閑扯！請轉換成 push-style，尤其在 GitHub 這個協同天堂：

對要討論的內容，延續 mailing-list 的禮儀 ，採用 inline reply 或 Bottom-posting 的格式逐一回復觀點，比如

除了 assignee，其他人也自覺維護 Issue ，把已形成的共識及時更新到首個 comment 中，以便其他打開這個 Issue 的夥伴可以快速知曉進展

若 Issue 完成，及時 close ，讓人進入 Issues 主界面即可及時知曉目前正在進行的 Issue。為啥？謹記大媽督導：

Issue 是過程討論，盡量消滅 Issue

長期復用的一切文案,要用 維基/倉庫 收集

Issue 永遠只是暫時性任務的追蹤/提醒/討論!

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！