续 - 关于好好写doc

本人写了这个贴子
https://www.1point3acres.com/bbs/thread-910737-1-1.html
今天又看到这个https://www.1point3acres.com/bbs/thread-918757-1-1.html
想起来最近我身旁发生的小事，给大家记下来，再次强调doc的重要性。没有干货，就是流水账。

本人最近为组里设置一个服务，需要登陆某个系统。当时mentor，一个很耐心的前辈，给我一步步讲了如何configure，至少花了半个小时。但是有个问题：有个东西我没有权限，mentor本人也不清楚（毕竟他开权限也是好久之前了）。我搜了一段时间，找到了合适的人，然后设置好了。

我把整个的设置过程一步步写了doc，为了我之后交接的时候方便。

前几天听说，就在我设置之后，组里另一个新人需要同样的系统。那个mentor也是给他一步步讲如何做，那个新人碰到了同样的问题，不幸的是他没找到合适的人，block了好久，我的manager和skip manager在帮他问。我知道了之后，立马share给了组里doc，他也找到了联系方式。

结论：
1. 如果mentor把整个过程写下来，或者他的学生详细记了个doc，我mentor根本不用一遍遍地开会讲设置，每个新人，对他来说都可以省下30分钟的时间。而写doc，根本用不了很久（因为他在讲解的时候，有的步骤也要现想/有的平台比较慢/需要打command...)。
2. 正如 https://www.1point3acres.com/bbs/thread-918757-1-1.html，doc要非常详细，确保一个啥都不懂的也能一步一步做对。权限其实就是一封邮件的事，但如果不知道找谁就抓瞎了，导致后续无法进行。像我mentor，几年之后再想，可能就忘了该找哪个组了。
3. 新人，如果你们组里有个很能写doc的人，有事问问他，说不定有惊喜。

这其实和refactor一样，如果一件事大概率以后要重复，就应该独立成一个方法，或者这里说的文档。don’t repeat yourself 不是最基本的要求吗？

有一份很详细的doc 真的很重要！有的doc 关键步骤都有，但前因后果一带而过，设置的时候还是很令人茫然

BZH 发表于 2022-8-11 21:05
这其实和refactor一样，如果一件事大概率以后要重复，就应该独立成一个方法，或者这里 ...

insightful!