你们写文档吗 - V2EX
V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
ljzxloaf
V2EX    职场话题

你们写文档吗

  •  
  •   ljzxloaf 2023-11-23 22:07:17 +08:00 3628 次点击
    这是一个创建于 733 天前的主题,其中的信息可能已经有所发展或是发生改变。
    我们组几乎没有文档,业务只存在于三位“元老”脑中。他们随便走一位,业务都得黄。

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

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

    不知道大家是怎么让新队友快速熟悉业务的?是通过文档吗?还是让 ta“自学成才”?如果是通过文档,那么是怎样保持文档的“新鲜度”的呢?
    36 条回复    2023-11-24 23:26:54 +08:00
    taogen
        1
    taogen  
       2023-11-23 22:52:04 +08:00
    写文档不算工作量,上级不会安排人去写文档,写文档全靠自己用爱发电。所以,写文档的人要找到写的目的和动力。

    写文档,你得能写,有时间写,愿意写。
    ljzxloaf
        2
    ljzxloaf  
    OP
       2023-11-23 23:01:55 +08:00
    @taogen #1 算不算工作量还不是领导一句话的事儿
    ljzxloaf
        3
    ljzxloaf  
    OP
       2023-11-23 23:03:11 +08:00
    @taogen #1 我感觉有的人已经是故意不写文档了,从而保持自己的“竞争力”,业务离不了
    yeqizhang
        4
    yeqizhang  
       2023-11-23 23:08:41 +08:00 via Android
    没时间写。别人的代码也只能自己摸索
    zsj1029
        5
    zsj1029  
       2023-11-23 23:15:13 +08:00 via iPhone
    文档写一周,写代码可能用不了一周,不过写文档可以细化开发细节,加深业务思考与理解,各取所需吧,项目不急就从这文档开始吧
    loveumozart
        6
    loveumozart  
       2023-11-23 23:16:33 +08:00
    需要写才写,不需要写就不写。

    新队友快速熟悉业务 = 不需要
    领导让给新队友串讲业务 = 需要
    xuanbg
        7
    xuanbg  
       2023-11-24 07:49:24 +08:00
    hunterzhang86
        8
    hunterzhang86  
       2023-11-24 08:14:37 +08:00 via iPhone
    我会要求组员都要写,当然也是为了大家说的避免人员流失带来的影响。另外一个重要原因就是减少沟通成本,也帮助开发把东西沉淀下来。
    thinkm
        9
    thinkm  
       2023-11-24 08:40:23 +08:00
    写文档时间远大于写代码
    dengji85
        10
    dengji85  
       2023-11-24 08:53:03 +08:00
    领导任务根本不考虑你写文档的工作量,修复 bug 也是开发任务工作量挤出来的,谁愿意写
    QUC062IzY3M1Y6dg
        11
    QUC062IzY3M1Y6dg  
       2023-11-24 08:57:55 +08:00
    我这每做一个项目都让我写好文档 程序员最讨厌的事情
    libasten
        12
    libasten  
       2023-11-24 09:04:57 +08:00
    写吧,写文档,也是一个程序员需要的能力,也是是对沟通能力的锻炼。
    litchinn
        13
    litchinn  
       2023-11-24 09:05:11 +08:00
    理想情况肯定是要写的,但现实情况是大多数开发没有写文档的时间,开发流程中也没有写设计这一块,项目参与人数不多,文档体现不出重要性

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

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

    只有把文档当作开发流程中重要的一环,和测试一样列入 QA 体系,才能保证这个文档的“新鲜度”
    cp19890714
        14
    cp19890714  
       2023-11-24 09:26:21 +08:00
    写. 需求评审完, 开始写文档, 然后评审文档, 通过后, 才能开始编码.
    处理文档, 通常需要 1-4 天.
    xiaoHuaJia
        15
    xiaoHuaJia  
       2023-11-24 09:30:18 +08:00
    写但是不会公开,首先写文档不算工作量,也不会多给钱,再次写文档就会降低我在这个工作多年的工作经验的价值。别人什么样我无所谓。除非公司强制说要写文档,不然我会自己写在个人的文档,有问题自己查。
    不然随便新人就可以替代你何必呢,做人自私一点。我进来的时候还不是都靠自己慢慢理解,到你这里为啥我一定要贡献出我的所有经验?你给我钱么
    cp19890714
        16
    cp19890714  
       2023-11-24 09:30:53 +08:00
    @cp19890714
    文档内容:
    * 需求分析
    * 模型设计
    * API 设计. 包含详细的逻辑, 对于复杂业务, 需要写出详细逻辑.
    * 测试用例
    * 难点, 问题点,
    * 发布流程.

    文档足够详细, 估时也就足够准确, 大家也就不用加班.
    xmt328
        17
    xmt328  
       2023-11-24 09:39:38 +08:00
    @ljzxloaf #3 就算是真的我觉得也没问题,凭啥只让公司耍流氓,到自己就开始道德评判了
    fredweili
        18
    fredweili  
       2023-11-24 09:41:28 +08:00
    都是被迫写的,写了普通用户也很难理解
    CodeCodeStudy
        19
    CodeCodeStudy  
       2023-11-24 09:43:53 +08:00
    写啊,主要是写个自己看,自己写文档,方便以后工作的时候快速定位问题。不要给领导和其他岗位的人看,给不给同组的工程师看,主要是看关系和心情。
    lyxxxh2
        20
    lyxxxh2  
       2023-11-24 09:44:17 +08:00
    不写 写也是给自己看逻辑
    跟同事说 为什么要左这个需求 -> 业务逻辑 -> 代码区块讲解。
    比如:
    1. 需求最终目的。
    2. 大概怎么样实现目的。
    3. 这块代码作用 下一块代码作用
    jydeng
        21
    jydeng  
       2023-11-24 09:46:59 +08:00   1
    文档有利于梳理思路和记录,写文档->评审回归->开发->提测,尽量按照这个流程来,有价值的还可以开个分享提升影响力。
    kkkbbb
        22
    kkkbbb  
       2023-11-24 09:48:05 +08:00
    文档这事,典型的别人不写 mmp ,自己不写乐叽叽
    ColdBird
        23
    ColdBird  
       2023-11-24 09:48:13 +08:00   1
    文档能力也是工作能力的一部分,只会写代码是不行的,况且很多连代码都写不好的
    wumoumou
        24
    wumoumou  
       2023-11-24 09:49:46 +08:00
    @zsj1029 大佬一般都是用什么工具写文档呢?
    tool2d
        25
    tool2d  
       2023-11-24 09:54:08 +08:00
    我看有些老外很喜欢把文档写在代码注释里,再用工具批量提取。
    o562dsRcFqYl375i
        26
    o562dsRcFqYl375i  
       2023-11-24 10:00:37 +08:00
    感觉写不难,难的是后续的维护更新
    nevermoreluo
        27
    nevermoreluo  
       2023-11-24 10:19:01 +08:00
    对接的对象多写文档能有效降低沟通成本。
    不过,维护时更新就很麻烦,所以我一般都是不写,要写就项目注释通过 ci 生成文档,文档跟着项目走。
    有新的项目对接直接给文档地址,降低很多沟通成本。
    doxygen+swagger 再给提供一些小的测试工具可以自定义发包的基本够用了
    iOCZS
        28
    iOCZS  
       2023-11-24 10:31:53 +08:00
    听上去有点像少林寺的三位圣僧
    zsj1029
        29
    zsj1029  
       2023-11-24 10:33:17 +08:00 via iPhone
    @wumoumou word 即可,可以让 poe 梳理下大纲,细节自己补充
    fantathat
        30
    fantathat  
       2023-11-24 10:45:00 +08:00 via iPhone
    一般新项目在立项之初就没有文档,忽悠用户就只交互可运行的代码。一般老项目为了运行和维护需要有操作文档,这样比较标准不容易出事。文档由于规范了操作行为,这样就降低了管理的灵活度,显得管理无用,因此无法用此法来管理。所以你说写不写文档,应不应该写文档,以及谁来写写给谁
    wenerme
        31
    wenerme  
       2023-11-24 10:51:00 +08:00
    写,业务文档减少沟通时间,技术文档作为个人积累。
    业务文档 泛化 后也能作为个人积累,例如 https://www.wener.tech/notes/service/erp/faq
    815979670
        32
    815979670  
       2023-11-24 11:03:37 +08:00
    写 而且我喜欢写文档,写开发文档的时候会把流程再过一遍,有时候还能发现 bug 。
    ljzxloaf
        33
    ljzxloaf  
    OP
       2023-11-24 13:02:59 +08:00
    @litchinn #13 老员工也没有跟你把业务合盘脱出的义务啊,除非这事算绩效,你看贴子里就有老员工不愿意分享文档,“毕竟当年是 ta 花时间整理的”,不是所有人都有那么高的格局的,尤其是在一个 leader 格局也不高的团队里。文档至少能保证下限,不太受个别敝帚自珍的人的影响。
    ljzxloaf
        34
    ljzxloaf  
    OP
       2023-11-24 13:09:11 +08:00
    @zsj1029 #5 开始写肯定比较慢,渐渐的套路摸清了就快了。而且文档这事丰俭由人,也不一定写得多面面俱到,让读者在短时间内对业务有个大致的理解就可以了。细节的部分需要 trace 需求文档、设计文档等,当然这种文档需要通过某种方式跟代码关联起来。
    zsj1029
        35
    zsj1029  
       2023-11-24 13:14:50 +08:00
    @ljzxloaf 这个你说的有道理,但是确实写得很细,应该叫详细设计文档,每个 api 规范约定很细,这样子开发人员照着写,新手也能很快上路,甚至无需了解业务细节
    wumoumou
        36
    wumoumou  
       2023-11-24 23:26:54 +08:00
    @zsj1029 poe ?流放之路吗? 大佬也玩流放之路吗?
    关于     帮助文档     自助推广系统     博客     API     FAQ     Solana     2877 人在线   最高记录 6679       Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 28ms UTC 14:21 PVG 22:21 LAX 06:21 JFK 09:21
    Do have faith in what you're doing.
    ubao msn snddm index pchome yahoo rakuten mypaper meadowduck bidyahoo youbao zxmzxm asda bnvcg cvbfg dfscv mmhjk xxddc yybgb zznbn ccubao uaitu acv GXCV ET GDG YH FG BCVB FJFH CBRE CBC GDG ET54 WRWR RWER WREW WRWER RWER SDG EW SF DSFSF fbbs ubao fhd dfg ewr dg df ewwr ewwr et ruyut utut dfg fgd gdfgt etg dfgt dfgd ert4 gd fgg wr 235 wer3 we vsdf sdf gdf ert xcv sdf rwer hfd dfg cvb rwf afb dfh jgh bmn lgh rty gfds cxv xcv xcs vdas fdf fgd cv sdf tert sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf shasha9178 shasha9178 shasha9178 shasha9178 shasha9178 liflif2 liflif2 liflif2 liflif2 liflif2 liblib3 liblib3 liblib3 liblib3 liblib3 zhazha444 zhazha444 zhazha444 zhazha444 zhazha444 dende5 dende denden denden2 denden21 fenfen9 fenf619 fen619 fenfe9 fe619 sdf sdf sdf sdf sdf zhazh90 zhazh0 zhaa50 zha90 zh590 zho zhoz zhozh zhozho zhozho2 lislis lls95 lili95 lils5 liss9 sdf0ty987 sdft876 sdft9876 sdf09876 sd0t9876 sdf0ty98 sdf0976 sdf0ty986 sdf0ty96 sdf0t76 sdf0876 df0ty98 sf0t876 sd0ty76 sdy76 sdf76 sdf0t76 sdf0ty9 sdf0ty98 sdf0ty987 sdf0ty98 sdf6676 sdf876 sd876 sd876 sdf6 sdf6 sdf9876 sdf0t sdf06 sdf0ty9776 sdf0ty9776 sdf0ty76 sdf8876 sdf0t sd6 sdf06 s688876 sd688 sdf86