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

你们写文档吗

  •  
  •   ljzxloaf · 350 天前 · 2937 次点击
    这是一个创建于 350 天前的主题,其中的信息可能已经有所发展或是发生改变。
    我们组几乎没有文档,业务只存在于三位“元老”脑中。他们随便走一位,业务都得黄。

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

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

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

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

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

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

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

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

    文档足够详细, 估时也就足够准确, 大家也就不用加班.
    xmt328
        17
    xmt328  
       350 天前
    @ljzxloaf #3 就算是真的我觉得也没问题,凭啥只让公司耍流氓,到自己就开始道德评判了
    fredweili
        18
    fredweili  
       350 天前
    都是被迫写的,写了普通用户也很难理解
    CodeCodeStudy
        19
    CodeCodeStudy  
       350 天前
    写啊,主要是写个自己看,自己写文档,方便以后工作的时候快速定位问题。不要给领导和其他岗位的人看,给不给同组的工程师看,主要是看关系和心情。
    lyxxxh2
        20
    lyxxxh2  
       350 天前
    不写 写也是给自己看逻辑
    跟同事说 为什么要左这个需求 -> 业务逻辑 -> 代码区块讲解。
    比如:
    1. 需求最终目的。
    2. 大概怎么样实现目的。
    3. 这块代码作用 下一块代码作用
    jydeng
        21
    jydeng  
       350 天前   ❤️ 1
    文档有利于梳理思路和记录,写文档->评审回归->开发->提测,尽量按照这个流程来,有价值的还可以开个分享提升影响力。
    kkkbbb
        22
    kkkbbb  
       350 天前
    文档这事,典型的别人不写 mmp ,自己不写乐叽叽
    ColdBird
        23
    ColdBird  
       350 天前   ❤️ 1
    文档能力也是工作能力的一部分,只会写代码是不行的,况且很多连代码都写不好的
    wumoumou
        24
    wumoumou  
       350 天前
    @zsj1029 大佬一般都是用什么工具写文档呢?
    tool2d
        25
    tool2d  
       350 天前
    我看有些老外很喜欢把文档写在代码注释里,再用工具批量提取。
    o562dsRcFqYl375i
        26
    o562dsRcFqYl375i  
       350 天前
    感觉写不难,难的是后续的维护更新
    nevermoreluo
        27
    nevermoreluo  
       350 天前
    对接的对象多写文档能有效降低沟通成本。
    不过,维护时更新就很麻烦,所以我一般都是不写,要写就项目注释通过 ci 生成文档,文档跟着项目走。
    有新的项目对接直接给文档地址,降低很多沟通成本。
    doxygen+swagger 再给提供一些小的测试工具可以自定义发包的基本够用了
    iOCZS
        28
    iOCZS  
       350 天前
    听上去有点像少林寺的三位圣僧
    zsj1029
        29
    zsj1029  
       350 天前 via iPhone
    @wumoumou word 即可,可以让 poe 梳理下大纲,细节自己补充
    fantathat
        30
    fantathat  
       350 天前 via iPhone
    一般新项目在立项之初就没有文档,忽悠用户就只交互可运行的代码。一般老项目为了运行和维护需要有操作文档,这样比较标准不容易出事。文档由于规范了操作行为,这样就降低了管理的灵活度,显得管理无用,因此无法用此法来管理。所以你说写不写文档,应不应该写文档,以及谁来写写给谁
    wenerme
        31
    wenerme  
       350 天前
    写,业务文档减少沟通时间,技术文档作为个人积累。
    业务文档 泛化 后也能作为个人积累,例如 https://www.wener.tech/notes/service/erp/faq
    815979670
        32
    815979670  
       350 天前
    写 而且我喜欢写文档,写开发文档的时候会把流程再过一遍,有时候还能发现 bug 。
    ljzxloaf
        33
    ljzxloaf  
    OP
       350 天前
    @litchinn #13 老员工也没有跟你把业务合盘脱出的义务啊,除非这事算绩效,你看贴子里就有老员工不愿意分享文档,“毕竟当年是 ta 花时间整理的”,不是所有人都有那么高的格局的,尤其是在一个 leader 格局也不高的团队里。文档至少能保证下限,不太受个别敝帚自珍的人的影响。
    ljzxloaf
        34
    ljzxloaf  
    OP
       350 天前
    @zsj1029 #5 开始写肯定比较慢,渐渐的套路摸清了就快了。而且文档这事丰俭由人,也不一定写得多面面俱到,让读者在短时间内对业务有个大致的理解就可以了。细节的部分需要 trace 需求文档、设计文档等,当然这种文档需要通过某种方式跟代码关联起来。
    zsj1029
        35
    zsj1029  
       350 天前
    @ljzxloaf 这个你说的有道理,但是确实写得很细,应该叫详细设计文档,每个 api 规范约定很细,这样子开发人员照着写,新手也能很快上路,甚至无需了解业务细节
    wumoumou
        36
    wumoumou  
       349 天前
    @zsj1029 poe ?流放之路吗? 大佬也玩流放之路吗?
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   4754 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 28ms · UTC 09:50 · PVG 17:50 · LAX 01:50 · JFK 04:50
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.