你们写文档吗

[ljzxloaf]

我们组几乎没有文档，业务只存在于三位“元老”脑中。他们随便走一位，业务都得黄。

产品需求文档是有的，但是也不知道跟代码是怎么对应的，而且也不知道全不全。

之前在外包公司呆的时候，虽然那个时候还没用 git ，但是文件的每次改动都要将需求链接或者 bug 链接写在文件的注释里，后来者通过需求文件很容易理解业务全貌。现在基本只能靠跟“前辈”讨教或者自己读代码，犹如盲人摸象，只能获得一些残缺不全的业务认知。

不知道大家是怎么让新队友快速熟悉业务的？是通过文档吗？还是让 ta“自学成才”？如果是通过文档，那么是怎样保持文档的“新鲜度”的呢？

[jydeng]

文档有利于梳理思路和记录，写文档->评审回归->开发->提测，尽量按照这个流程来，有价值的还可以开个分享提升影响力。

[kkkbbb]

文档这事，典型的别人不写 mmp ，自己不写乐叽叽

[ColdBird]

文档能力也是工作能力的一部分，只会写代码是不行的，况且很多连代码都写不好的

[wumoumou]

@zsj1029 大佬一般都是用什么工具写文档呢？

[tool2d]

我看有些老外很喜欢把文档写在代码注释里，再用工具批量提取。

[o562dsRcFqYl375i]

感觉写不难，难的是后续的维护更新

[nevermoreluo]

对接的对象多写文档能有效降低沟通成本。
不过，维护时更新就很麻烦，所以我一般都是不写，要写就项目注释通过 ci 生成文档，文档跟着项目走。
有新的项目对接直接给文档地址，降低很多沟通成本。
doxygen+swagger 再给提供一些小的测试工具可以自定义发包的基本够用了

[iOCZS]

听上去有点像少林寺的三位圣僧

[zsj1029]

@wumoumou word 即可，可以让 poe 梳理下大纲，细节自己补充

[fantathat]

一般新项目在立项之初就没有文档，忽悠用户就只交互可运行的代码。一般老项目为了运行和维护需要有操作文档，这样比较标准不容易出事。文档由于规范了操作行为，这样就降低了管理的灵活度，显得管理无用，因此无法用此法来管理。所以你说写不写文档，应不应该写文档，以及谁来写写给谁

[wenerme]

写，业务文档减少沟通时间，技术文档作为个人积累。
业务文档 泛化 后也能作为个人积累,例如 https://www.wener.tech/notes/service/erp/faq

[815979670]

写 而且我喜欢写文档，写开发文档的时候会把流程再过一遍，有时候还能发现 bug 。

[ljzxloaf]

@litchinn #13 老员工也没有跟你把业务合盘脱出的义务啊，除非这事算绩效，你看贴子里就有老员工不愿意分享文档，“毕竟当年是 ta 花时间整理的”，不是所有人都有那么高的格局的，尤其是在一个 leader 格局也不高的团队里。文档至少能保证下限，不太受个别敝帚自珍的人的影响。

[ljzxloaf]

@zsj1029 #5 开始写肯定比较慢，渐渐的套路摸清了就快了。而且文档这事丰俭由人，也不一定写得多面面俱到，让读者在短时间内对业务有个大致的理解就可以了。细节的部分需要 trace 需求文档、设计文档等，当然这种文档需要通过某种方式跟代码关联起来。

[zsj1029]

@ljzxloaf 这个你说的有道理,但是确实写得很细,应该叫详细设计文档,每个 api 规范约定很细,这样子开发人员照着写,新手也能很快上路,甚至无需了解业务细节

[wumoumou]

@zsj1029 poe ？流放之路吗？ 大佬也玩流放之路吗？