GitHub 协作五大业余姿势

协作姿势业余虽不至酿成大错，但着实让人浑身不自在。
本文复盘俺过往踩坑经历（其实就是被 @ZoomQuiet 大妈咆哮调教的血泪史），
助你规避几大常见业余姿势、少走弯路，更快体会 GitHub 协作的舒爽乐趣。

近期看到不少同伴使用 GitHub 协作，我开始理解当初 @ZoomQuiet 大妈和我协作时的痛苦感受----这不顺眼那不专业，比如用中文命名、创建 wiki 却不更新 sidebar、满屏 Issue 不及时 close、Issue 通篇没有一个超链接等，虽不至酿成大错，但实在让人浑身不自在。遂复盘自己踩坑经历（其实就是被大妈咆哮调教的血泪史 T_T）供你规避几大常见业余姿势，少走弯路，更快体会 GitHub 协作的舒爽乐趣。

注意：

若不了解 GitHub 是什么，请先移步 GitHub 基础教程：
- 简明 GitHub 练级攻略：我写的非技术人员 GitHub 使用指南
- GitHub Guides：官方图文版科普
本文所列建议主要针对非技术协作的知识管理型团队，如果你对所在团队是否是知识管理型团队无所谓，这篇文章不必往下看了;-)

嗯哼，如果以上两坎你都越过，那来看看我被咆哮嫌弃 N 次的业余姿势你中了几个吧……

用中文命名 wiki 或文件

为什么?! 为什么?! 为什么?! 为什么?! 为什么?! 为什么?! 为什么?! 为什么?! 为什么?! 为什么?!

要用中文名的文件呢?!?!?!??

在 GitHub 世界或是其它任意计算机世界中,

使用非 ASCII 字串为文件名,

都象在华尔街高声显摆刚刚买咸菜占了两毛銭便宜!

恶俗到突破天际的行为!

初次创建 wiki ，我以中文命名，被大妈在协作群里如是咆哮，记忆深刻。

由于更熟悉汉语，或不知道该以什么英文命名，不少人和我当初一样，下意识用中文命名文档。这是新手最常出现的姿势，尤其没有技术背景的新手。

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

对比一下由此生成的 wiki pages URL 就知道了
- wiki title 为「Test」的页面：https://github.com/sunnyhuang42/example/wiki/Test
- wiki title 为「测试」的页面：https://github.com/sunnyhuang42/example/wiki/%E6%B5%8B%E8%AF%95
- 你觉得哪个 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.）等信息，以便同伴快速理解调用。比如：

标题比正文更重要，别漏了！

更多创建文档的建议，可以参考这个协作文档撰写指南。

多写几行字你嫌麻烦？

那是你没考虑时间的复利效应啊——

对，在私人目录建个文案自己看，自己记得创建了什么/用于什么场合/怎么命名，需要的时候及时找到就好。

但在团队界面，你创建的东西，通常还需同伴知晓/修订/审核/使用，而且涉及不止一位伙伴。考虑人数和时间的几何叠加，啧啧，这省下来的成本，值得叫老板给你加薪~

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 永远只是暂时性任务的追踪/提醒/讨论!

当然，close Issue 不能点击 close 就完事儿，请在 comment 中附上相关链接，以便继续追踪这个议题