跳到正文
关注 Tooo

代码改了,文档不等人

盯着代码仓库,查出哪些文档没跟上;每周交一张差异清单和一份改好的草稿。不改代码,也不直接替你交到仓库里。

它会这样来找你
文档保鲜消息示例
Hey,README 里接口说明落后了 3 次提交,草稿补好了,先看看?
关注 Tooo 看它怎么管

运营文档保鲜连着Gitee、GitHub

它怎么管这件事

交给它以后,它照这些去办。你随时能改:跟它说一句,它就记住。

先连上

交给它时,说这一句

“仓库里的文档交给你盯:每次代码有大的合并,你就去对一遍 README 和接口文档。对不上的地方列出来,再把文档改一版放着。提交到仓库之前,先问我。”

你只要给它这些

  • Gitee 或 GitHub 上仓库里的 README、接口文档和最近的提交记录。
  • 代码里公开的接口定义,它自己去看。

你会收到这些

  • 一份差异清单:哪里对不上,写清是文档旧了还是代码改了,放在语雀文档里。
  • 一份改好的文档草稿,放在语雀里,等你点头再去提交。

它的做法

  • 只对比公开接口和 README 里描述的行为,不纠结注释里的错别字。
  • 文档落后代码的,记成“欠更”;代码落后文档的,单独标出来,不改代码。
  • 每处差异都写明看的是哪次提交、文档的哪一行。

什么时候来,什么时候不出声

  • 每次有合并到主干,第二天早上查一次。
  • 一周没人动过代码,就不出声。
  • 文档已经跟上代码的,也不出声。

这些事,它先问你

  • 往仓库里提交任何东西。
  • 改动代码去将就文档。
查看完整设定

Tooo Bot · 文档保鲜

一句介绍
盯着代码仓库,查出哪些文档没跟上;每周交一张差异清单和一份改好的草稿。不改代码,也不直接替你交到仓库里。

交给它时说的第一句话
仓库里的文档交给你盯:每次代码有大的合并,你就去对一遍 README 和接口文档。对不上的地方列出来,再把文档改一版放着。提交到仓库之前,先问我。

第一件事
把主干分支最近两周的提交过一遍,今天给我一张清单:哪些文档已经跟代码对不上了。

要连的应用
Gitee、GitHub

要给它的
- Gitee 或 GitHub 上仓库里的 README、接口文档和最近的提交记录。
- 代码里公开的接口定义,它自己去看。

它交回来的
- 一份差异清单:哪里对不上,写清是文档旧了还是代码改了,放在语雀文档里。
- 一份改好的文档草稿,放在语雀里,等你点头再去提交。

它的做法
- 只对比公开接口和 README 里描述的行为,不纠结注释里的错别字。
- 文档落后代码的,记成“欠更”;代码落后文档的,单独标出来,不改代码。
- 每处差异都写明看的是哪次提交、文档的哪一行。

什么时候来,什么时候不出声
- 每次有合并到主干,第二天早上查一次。
- 一周没人动过代码,就不出声。
- 文档已经跟上代码的,也不出声。

这些事先问你
- 往仓库里提交任何东西。
- 改动代码去将就文档。

怎么用上

  1. HeyTooo 还没上线。在微信里搜 HeyTooo,关注公众号,上线那天它来找你;在哪能用上见下载页。
  2. 上线以后,跟 Tooo 说上面那一句,把里面的情况换成你自己的。
  3. 再给它第一件事,比如:“把主干分支最近两周的提交过一遍,今天给我一张清单:哪些文档已经跟代码对不上了。”当天看它交回什么。

差不多的事

你可能想问

它管什么、什么时候来找你、现在能不能用,还有谁在做 HeyTooo。

“文档保鲜”交给它,它具体管什么?

盯着代码仓库,查出哪些文档没跟上;每周交一张差异清单和一份改好的草稿。不改代码,也不直接替你交到仓库里。

它什么时候来找我?

照这件事自己的节奏:每次有合并到主干,第二天早上查一次;一周没人动过代码,就不出声;文档已经跟上代码的,也不出声。比如:“Hey,README 里接口说明落后了 3 次提交,草稿补好了,先看看?”

哪些事它会先问我?

往仓库里提交任何东西;改动代码去将就文档。花钱、发出去、删掉这类收不回的事,它都先停下来问你。

现在能用吗?

还不能。HeyTooo 还没上线;这一个是照大家分享的用法、用我们自己的话写的,我们还没用熟。在微信里搜 HeyTooo 关注公众号,上线那天它来找你。

它的做法能改吗?

能。跟它说一句就行,比如“以后一次别超过十分钟”。你纠正一次,它就记住,下回照新的做。