写点什么

文档是给未来自己的珍贵礼物

用户头像
steve_lee
关注
发布于: 2021 年 03 月 23 日
文档是给未来自己的珍贵礼物

80%的时间工作,并留 20%的时间来写文档,比 120%的时间写代码长处产出要高的多。


在开发过程中,文档总很多程序员是最不愿意触碰的部分,甚至超过了测试用例。但是本人工作中和阅读的书籍,都用很多实例来证明,文档真的是生产力工具。


不愿意写文档的原因很多,1. 业务变更快,还没等写完业务变了,代码也变了; 2. 随着进度开发,会有很多重构工作,此时之前写完的文档就是拖油瓶,看着累写着更累;3. 等业务稳定了在写,但是业务稳定了觉得写了的很多也没人看,白费劲;4. 领导不重视,不会有产出,像是杂活;5.对于内部竞争激烈的团队,写文档方便别人,耽误自己产出,3.25 不给你给谁?


写文档的好处其实更多:1. 业务变更快,那么不变的部分,如果记录下来,后面拿起来的时候,就有了很好的指南,不用从聊天记录等地方去找操作指南;2. 文档是很好的沟通工具,在团队协作中,有一份文档,整体效率是高出很多的,是一件通过利他而利己的事情,后其身而身先的事;3.对于搁置了超过 3 个月的项目,如果需要重新开发,哪怕是自己写的,大概率也想不起来了,此时有一个文档,真的会感谢自己的。4.文档相当于后勤保障,一直写代码,孤军突进当然好,但是没有配套后勤,走不太远,也很难写太大的项目(涉及团队合作,涉及长期开发,总不能别人有问题就问你)。 5.对工程师来说,logbook 是一个基本素养,在外企工作过程中,发现老外的文档写的明显更全面,没有感觉他们智力优势,短期看,效率还挺慢的,但是做出来的项目,确实更加完备。

那么怎么做才能写文档呢?1. 首先有一个开放平等友善的氛围,如果处在内部竞争激烈的场景,写不写文档就看你自己的斗争策略了;2. 强制自己每周花 3-4 个小时写文档,可以每天写,也可以完成一个模块添加上面;周五也把剩下的进行收尾;并且修改过期的文档。


文档可以写什么?软件使用说明书,开发或使用软件的用法,变更的通信协议,自己踩过以为已经记住但是还是会遇到的坑,模型训练的 trick 记录,多种训练方法的 loss 对比,客户或者内部使用产品给出的评价等,咨询专家后获取的知识库。


就到这里,知行合一很难,希望读者和笔者都会坚持写文档,千万别孤军冒进。


发布于: 2021 年 03 月 23 日阅读数: 11
用户头像

steve_lee

关注

还未添加个人签名 2018.03.09 加入

还未添加个人简介

评论

发布
暂无评论
文档是给未来自己的珍贵礼物