你们写文档吗

[ljzxloaf]

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

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

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

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

[taogen]

写文档不算工作量，上级不会安排人去写文档，写文档全靠自己用爱发电。所以，写文档的人要找到写的目的和动力。

写文档，你得能写，有时间写，愿意写。

[ljzxloaf]

@taogen #1 算不算工作量还不是领导一句话的事儿

[ljzxloaf]

@taogen #1 我感觉有的人已经是故意不写文档了，从而保持自己的“竞争力”，业务离不了

[yeqizhang]

没时间写。别人的代码也只能自己摸索

[zsj1029]

文档写一周，写代码可能用不了一周，不过写文档可以细化开发细节，加深业务思考与理解，各取所需吧，项目不急就从这文档开始吧

[loveumozart]

需要写才写，不需要写就不写。

新队友快速熟悉业务 = 不需要
领导让给新队友串讲业务 = 需要

[xuanbg]

我们这文档是有的，但不多……

[hunterzhang86]

我会要求组员都要写，当然也是为了大家说的避免人员流失带来的影响。另外一个重要原因就是减少沟通成本，也帮助开发把东西沉淀下来。

[thinkm]

写文档时间远大于写代码

[dengji85]

领导任务根本不考虑你写文档的工作量，修复 bug 也是开发任务工作量挤出来的，谁愿意写

[shuxhan]

我这每做一个项目都让我写好文档 😭 程序员最讨厌的事情

[libasten]

写吧，写文档，也是一个程序员需要的能力，也是是对沟通能力的锻炼。

[litchinn]

理想情况肯定是要写的，但现实情况是大多数开发没有写文档的时间，开发流程中也没有写设计这一块，项目参与人数不多，文档体现不出重要性

文档有很多类型，首先是 PRD ，这个基本都是有的。
然后是设计文档
理想情况下由高级开发编写设计文档，中低级开发按照设计文档编码，一份好的设计文档应该阐述清楚业务需求是什么，为什么这么设计，有哪些注意事项，后续可能的变更会造成哪些影响
然后还有部署文档
最后还有使用手册，这个也很重要，不只是针对用户，对于新来的开发人员通过使用系统也能很快熟悉系统业务

以上多种文档组合才能达到通过文档来熟悉并快速入手项目的效果。
但从现实来看，大多数项目的参与人数没有那么多，花这么多时间写文档带来的效率提升并不好，而且文档质量低，文档更新不及时也是文档实施的阻碍，不如直接问老员工

只有把文档当作开发流程中重要的一环，和测试一样列入 QA 体系，才能保证这个文档的“新鲜度”

[cp19890714]

写. 需求评审完, 开始写文档, 然后评审文档, 通过后, 才能开始编码.
处理文档, 通常需要 1-4 天.

[xiaoHuaJia]

写但是不会公开，首先写文档不算工作量，也不会多给钱，再次写文档就会降低我在这个工作多年的工作经验的价值。别人什么样我无所谓。除非公司强制说要写文档，不然我会自己写在个人的文档，有问题自己查。
不然随便新人就可以替代你何必呢，做人自私一点。我进来的时候还不是都靠自己慢慢理解，到你这里为啥我一定要贡献出我的所有经验？你给我钱么

[cp19890714]

@cp19890714
文档内容:
* 需求分析
* 模型设计
* API 设计. 包含详细的逻辑, 对于复杂业务, 需要写出详细逻辑.
* 测试用例
* 难点, 问题点,
* 发布流程.

文档足够详细, 估时也就足够准确, 大家也就不用加班.

[xmt328]

@ljzxloaf #3 就算是真的我觉得也没问题，凭啥只让公司耍流氓，到自己就开始道德评判了

[fredweili]

都是被迫写的，写了普通用户也很难理解

[CodeCodeStudy]

写啊，主要是写个自己看，自己写文档，方便以后工作的时候快速定位问题。不要给领导和其他岗位的人看，给不给同组的工程师看，主要是看关系和心情。

[lyxxxh2]

不写 写也是给自己看逻辑
跟同事说 为什么要左这个需求 -> 业务逻辑 -> 代码区块讲解。
比如:
1. 需求最终目的。
2. 大概怎么样实现目的。
3. 这块代码作用 下一块代码作用

[jydeng]

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

[kkkbbb]

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

[ColdBird]

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

[wumoumou]

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

[tool2d]

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

[huangzongzhuan]

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

[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 ？流放之路吗？ 大佬也玩流放之路吗？