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

[吐槽贴]领导对于要求文档的详细程度到了偏执的程度

  •  
  •   Vaspike · 44 天前 · 6724 次点击
    这是一个创建于 44 天前的主题,其中的信息可能已经有所发展或是发生改变。
    • 矛盾

    核心矛盾: 工资待遇很不错

    写代码前要求我先把文档写出来,详实程度要求每个 service 中将会有哪些方法,共有私有

    开会的时间占到了工作时间的 50%左右

    领导是写代码出身,但每次开会和其他交流中都透露出对"写代码为低级工作,确定业务为高级工作"的看法

    我不否认他的某些想法,目前也会尽力完成他想要的东西,只是怕很多矛盾后面会越来越尖锐 最近和其他同事一起下班才知道部门其他同事也对他颇有微词,我进来时替换的这个岗位原来的开发就是被骂跑的

    第 1 条附言  ·  43 天前

    本身就是个吐槽贴,感谢大家的建议,我都认真看了,想通了很多

    79 条回复    2024-05-31 17:47:44 +08:00
    zhwq
        1
    zhwq  
       44 天前   ❤️ 1
    就当锻炼自己的文档能力了,后续对你帮助很大的。
    chaoschick
        2
    chaoschick  
       44 天前 via Android
    没有什么是不能习惯的
    Meteora626
        3
    Meteora626  
       44 天前
    写代码为低级工作,确定业务为高级工作 这句话没毛病,但是只要确定输入输出有啥就行了,写内部细节也太离谱了
    Mithril
        4
    Mithril  
       44 天前   ❤️ 17
    他的看法在大部分公司都是对的,毕竟造火箭的公司不多,CURD 能不能卖钱还是要靠业务。

    要是我的话,就想想怎么从代码提取出文档。

    要么自己改个 parser ,扫一遍代码列出所有 service 和方法,按照固定格式输出,然后自己添点东西改成文档。

    要么找个开源的 LLM ,看看能不能改造集成让它给我生成文档。一般来说这种固定格式的文档,你自己写个服务调个开源的 LLM ,调一下模型或者搞提示词应该能很好的解决。
    甚至你也可以反过来用文档生成代码。

    都搞定了就可以准备跳槽了。这次再跳至少不会说什么 “公司技术栈陈旧,没有学习机会” 了。
    locoz
        5
    locoz  
       44 天前   ❤️ 13
    有一说一,没太大问题...写业务代码就是低级工作,根据业务进行设计才是高级工作,只会写业务代码屁用没有。
    先写文档还是先写代码就是个风格、习惯的问题,各有优劣。但是在当下,先写一份设计清晰、描述详细的文档,是可以让 AI 快速解决代码的问题的,只要你的文档足够明确,AI 生成的代码跟你直接写的没区别,甚至可能更好,而且在整理思路上还会更优于边写代码边改。
    beimenjun
        6
    beimenjun  
       44 天前   ❤️ 1
    简明版:按照你的领导说的做

    ---------------------

    本来就是要做设计的,你如果设计的比较清晰,甚至到处文档这部分工作你甚至可以直接让 AI 辅助。

    如果“确定业务”意思是“搞清楚需求”,那我觉得优先级要比单纯“写代码”是应该排前面一些。

    至于开会 50% 也很正常,如果系统牵扯的人和部门比较多,就是要开会确认的,这些都是得开会确认的。你设计提交上去,估计也是要开会说明,pass 了才可能让你正式写,等到结束了还有回顾时间,50% 很夸张吗,其实还好。

    整体来说,按照你这个描述,我觉得你如果想吐槽,可能只是不适应。建议好好适应。
    TWorldIsNButThis
        7
    TWorldIsNButThis  
       44 天前 via iPhone   ❤️ 3
    日企出身?
    LawlietZ
        8
    LawlietZ  
       44 天前
    和你有类似经历,之前老板也是对文档要求很高,语句通不通顺都有要求,画图要求都很高,一个文档能改十几遍,确实难受,但确实也有提升,这种情况确实会导致下面员工离职率不低,只能说好好沟通面向老板输出吧,保证写文档时间够和薪资不错就行了
    wu00
        9
    wu00  
       44 天前
    “写代码前要求我先把文档写出来,详实程度要求每个 service 中将会有哪些方法,共有私有”只有少部分优秀的开发有这个能力
    haliluya
        10
    haliluya  
       44 天前
    经历过这么多年,很赞同“写代码为低级工作,确定业务为高级工作”这句话。代码实现,随便找个两三年工作经验的,基本上都可以胜任(普通功能需求,无高深逻辑算法,不犟)。但是如果找一个对业务很熟悉,一聊就明白的,很难,码农在一个公司长久的优势基本上就是业务理解了吧...个人偏见,不喜随便喷
    smdbh
        11
    smdbh  
       44 天前
    给时间照做就行了
    开始阶段,我觉得写文档和写代码都是一种设计结构的方法,写出来才能发现问题,逐步修改。这是管理者只愿意看图流程图之类的文档而已,没心思看代码。 除非是成熟项目,不然一次成型的概率太低了,最后还不是都要改
    watzds
        12
    watzds  
       44 天前
    @Mithril #4 以前数据库语句都要给 DBA 审核,我就是这样先写代码,再自动提取哈哈,文档写这些东西繁琐了
    heyjei
        13
    heyjei  
       44 天前   ❤️ 1
    "写代码为低级工作,确定业务为高级工作" 这句话没毛病。 业务代码最不值钱了,其包含的业务知识才值钱。
    Mithril
        14
    Mithril  
       44 天前   ❤️ 1
    @watzds 对的,所以其实工作是死的,但人是活的。

    自己在工作中研究点能提升自己工作效率的东西,工作就不会天天和上坟一样。只要工作能按时完成,大多数公司也不会阻止你做这些东西。

    反正工作就是那些,自己找点乐趣好了。
    darkengine
        15
    darkengine  
       44 天前
    这个是很自然的流程啊,只不过有些步骤之前是在脑子里过一遍,现在是要你写下来而已。
    cmsyh29
        16
    cmsyh29  
       44 天前
    你领导说的没错
    nomytwins
        17
    nomytwins  
       44 天前
    往往写代码的不这么认为"写代码为低级工作,确定业务为高级工作"。尤其是后端。
    murmur
        18
    murmur  
       44 天前
    哦,这不就是日式开发吗

    有幸看过某大型企业招标的代码要求,注释覆盖率 100%

    怎么说呢

    const six = 6 //66666666
    guanzhangzhang
        19
    guanzhangzhang  
       44 天前
    找一些框架按照代码生成文档,还能根据代码 tag 做版本管理😏
    azarasi
        20
    azarasi  
       44 天前
    可以用 doxygen 生成 xml 格式的文档,然后自己写一个程序解析生成领导要求的格式
    Tyrant1984
        21
    Tyrant1984  
       44 天前
    还行吧,我这边 SB 公司,写个周报老板甚至会挑你标点符号用的不够“标准”,比如分段数字序号后面必须用顿号,分段结束后必须用分号之类的,标点符号不能让他满意他就让你重写。
    anzu
        22
    anzu  
       44 天前 via iPhone
    业务驱动型项目是这样的。日企项目的文档才是详细到令人震惊,连方法内的代码也会在文档中以伪代码的形式描述出来。
    7lQM1uTy635LOmbu
        23
    7lQM1uTy635LOmbu  
       44 天前
    @Tyrant1984 #21 像极了我曾经做过的文档工程师
    huang86041
        24
    huang86041  
       44 天前
    和日企打过交道,很像日企的风格。
    NessajCN
        25
    NessajCN  
       44 天前   ❤️ 1
    论 Rust 的优越性...
    懂不懂 cargo doc 能省多少事啊....
    kneo
        26
    kneo  
       44 天前 via Android
    私有方法是不可能在设计阶段就确定的。甚至公有接口也往往不能在设计阶段就能完全确定。在设计阶段纠结过多末枝细节是会降低生产力的。

    当然,我有一个巧妙的方法,相信你也想到了。你先偷偷把代码写出来,然后作为设计提交上去。至于领导分配的写代码的时间,你可以去摸鱼,也可以提前去预测他下一阶段的设计。
    weofuh
        27
    weofuh  
       44 天前
    代码注释写详细点,再搞个工具,把注释提取出来就是文档了,哈哈哈哈。

    "写代码为低级工作,确定业务为高级工作" 个人觉得这个没啥毛病吧,前提是能真的确定好
    encro
        28
    encro  
       44 天前
    先设计再编码!

    这是锻炼从小工到大师的第一步,大师首先要做到的是胸有成竹,所谓心道手到,先心到然后做到手到,然后大师成。


    我就是这么训练自己和 chatgpt 的。
    先自己写伪代码,注释,然后将写代码变为填空。
    当我发现自己设计出错了,那么往往就又学到了。
    k9990009
        29
    k9990009  
       44 天前 via Android
    给时间就行。研究下那种类似 yapi 接口文档生成工具,将代码注释提取生成文档
    SoyaDokio
        30
    SoyaDokio  
       44 天前
    感觉是个很好的锻炼机会。
    业务万变不离其宗写来写去就那么些,唯有业务五花八门,理解稍有偏差就可能导致成果物相去甚远。

    另外文档这个东西是非常重要的,代码写多了可能就渐渐理解了。
    Tink
        31
    Tink  
       44 天前
    这些东西可以交给 gpt 来做
    kamilic
        32
    kamilic  
       44 天前
    其实挺好的,设计到位了,其实怎么实现都是差不多的样子
    silencil
        33
    silencil  
       44 天前
    大部分业务没有做设计的必要吧?很多接口,脑子里一过就知道是怎么回事,留个文档就是方便后续的人维护,但是文档很容易跟不上代码变更,初始的文档很可能又废了。
    yangzzzzzz
        34
    yangzzzzzz  
       44 天前   ❤️ 1
    写呗 反正算工时就行
    F7TsdQL45E0jmoiG
        35
    F7TsdQL45E0jmoiG  
       44 天前
    这详实程度确实不够高
    NICEghost
        36
    NICEghost  
       44 天前
    低级程序员,隐忍
    ZnductR0MjHvjRQ3
        37
    ZnductR0MjHvjRQ3  
       44 天前
    工资待遇很不错就够了,毕竟他这个问题又不是什么十恶不赦的问题,只是有点吃屎,而且你为啥非要按照他的流程走,不能自己先写一部分然后用 AI 搞定文档自己再删删改改吗,我倒是认为你们老板的想法没啥大问题,确定业务就是很重要,毕竟你再花里胡哨的业务,只要是正常的基本都有人实现过了,代码层面都有可参考的东西,毕竟码农就是...
    Huelse
        38
    Huelse  
       44 天前
    你领导没错,代码只是低级工作,你甚至可以交给刚毕业的大学生写,但实现设计并不是谁都能做好。

    等你写代码的时候更多考虑的是语法和语言特性,不会有太多思考逻辑的时间,这也是为什么要在开会和写文档的时候多思考,想好了再动手。
    mark2025
        39
    mark2025  
       44 天前
    抽象接口,方法用 swagger 加上输入输出备注,然后生成网页或者文档不行么?
    ShuWei
        40
    ShuWei  
       44 天前
    既然钱给够了,你还有啥好抱怨的,如果你是给工资的人,你可以决定工作方式,否则做好执行
    aikilan
        41
    aikilan  
       44 天前
    你的领导是对的
    Akiya
        42
    Akiya  
       44 天前   ❤️ 3
    文档要多详细暂且不说,稍微工作过几年都应该知道需求确定的过程比实际开发难多了,尤其现在 AI 这么强,你把需求写完以后基本上代码逻辑都不怎么需要自己动手了
    royking930911
        43
    royking930911  
       44 天前
    编码本身就是耗时低级的工作 设计才是软件的核心 设计文档写的好 工程师可以直接把编码的工作丢给应届生或者 ai 完成
    4ark
        44
    4ark  
       44 天前   ❤️ 1
    你觉得你应该庆幸你在这样的团队里面
    wanniwa
        45
    wanniwa  
       44 天前
    按你说的,文档设计完了,基本上伪代码都写完了,照着思路改成代码很快的。
    dif
        46
    dif  
       44 天前
    工资待遇很不错,干啥都行。开会时间多,怕是没有主题吧。一开会就发散。东拉西扯得问题都要在会上解决。
    liyafe1997
        47
    liyafe1997  
       44 天前
    这算好了,如果你去搞汽车电子,很多情况下文档/流程这些乱七八糟的东西甚至占到工作量的 80%,甚至专门有一个团队去做这些,人比开发团队多。
    lshbosheth
        48
    lshbosheth  
       44 天前
    给时间 就行 这种是很正确的流程啊 0.0 正常就应该开会时间大于开发时间 开会就把如何实现与波及分析都做了 写代码不就是按部就班嘛
    orioleq
        49
    orioleq  
       44 天前 via iPhone
    需求以业务为主导的软件开发流程确实是这样,如果需求分析和系统设计做得清晰,后面开发和测试都省力。这一点会跟以技术为主导的快速 demo 的项目完全不一样。
    如果是业务主导的开发 leader ,特别是只写思路代码交给小弟填充的,写设计文档这个能力是必须的吧。不然等代码都好了,再 review 再不断做 refactor ,又要搞好几轮,到时候挫败感更强。
    chanChristin
        50
    chanChristin  
       44 天前
    @Tyrant1984 这种就适合 ChatGPT 润色
    iyaozhen
        51
    iyaozhen  
       44 天前
    核心矛盾: 工资待遇很不错
    啥意思?工资给的高呗 那你还说啥

    [开会的时间占到了工作时间的 50%左右] 正常,当然具体要看会的内容
    "写代码为低级工作,确定业务为高级工作" 可以说很对了,没毛病

    矛盾这个我说个事情,之前有个很大的 leader 说,如果我推行一个决策,都需要和每个人解释清楚,那事情就做不了了。所以很简单,如果你工作没几年就跟着 leader 走。如果你本身已经有一套方法论了,和 leader 不合拍那就换个团队。
    Seria
        52
    Seria  
       44 天前
    只要不加班,那就是好的,只要加班,就算是再好的也是垃圾。
    yueyuea
        53
    yueyuea  
       44 天前
    挺好的,我认为 coding 占用我们的工作时间应该不超过百分之 20 ,剩余时间都应该在反复的思考和沟通(当然还有摸鱼)。有效的沟通加文档可以减少很多无意义 coding 时间,比所谓的靠加班来完成工作的 leader 强的不是一星半点。
    weilongs
        54
    weilongs  
       44 天前
    同感,但我这个领导不是纯写代码,是一个网络方面的出身,写过代码. 他的想法就是写代码基本上有手+baidu 就行了. 也是让我写文档灰常细致,以及他要学习怎么启动、调试. 我觉得他这想法就是一直做我的备份.是在备份不了也要找一个好接手.
    ArrayBuffer
        55
    ArrayBuffer  
       44 天前
    认同领导的做法, 我觉得核心的问题是文档是否物尽其用, 文档的可读性好不好, 维护工作是否能做好, 能让别人看懂的文档才是有价值的
    hitmanx
        56
    hitmanx  
       44 天前
    这个其实问题不大。是应该多花时间在设计上,设计阶段应该把所有的需求和未来的扩展性都考虑到,然后进行 review 。等到一切通过了,照着实现应该是很容易的。甚至设计和实现的可以不是同一个人。

    如果设计没有具体到另外一个人上手就能写代码的程度,说明设计还是不够具体。我工作过的几家外企,设计都是到这个程度的。

    但是国内的企业一半都是工期紧、任务重,很多东西都是没设计明白就键盘梭哈写代码了,回头再东改西改,这个其实是个坏的习惯。
    keakon
        57
    keakon  
       44 天前
    你们没经历过重构么?
    文档是不是也得重构啊?
    ZZITE
        58
    ZZITE  
       44 天前
    @keakon #56 有啥问题,你都把代码重构了,文档不重写吗?这不就是坑对接的人
    horizon
        59
    horizon  
       44 天前
    @Mithril #4
    你这明显违背了初衷
    要先写文档再写代码,而不是反过来
    keakon
        60
    keakon  
       44 天前
    @ZZITE 什么项目对接要看文档里的私有方法?你代码里用 IDE 几秒钟就重构完了,然后点开几百篇文档去替换字符串么?
    yuankui
        61
    yuankui  
       44 天前
    现在 AI 这么多,根据代码生成文档不难吧?
    BraveChi
        62
    BraveChi  
       44 天前
    1 、写文档要比写代码高级
    2 、领导在锻炼你
    3 、你干十年就知道了,去 tm 的写代码,还是写文档爽,谁干谁知道。文档可控,但是代码质量不可控啊。
    konakona
        63
    konakona  
       44 天前
    不清楚你的领导是否被讲不清内容的功能代码弄烦了,但是向上管理和自我驱动应是每一位优秀的开发者的职业素养才对。

    最好的办法是跟你的领导多次碰一碰,输出“技术文档的交付物”为何,以及如何进行质量评估来不断提升活文档的能力 —— 这对你、对你的领导,都是很好的做法和发展方向。

    你领导的性格可能就是这样的,要么接受他一起勾着,要么另谋高俅换组换领导。
    doommm
        64
    doommm  
       44 天前
    设计、接口文档可以写,私有的内部变量、方法这种涉及到实现细节的怎么事先写?设计的时候不能确定实现细节吧
    akira
        65
    akira  
       43 天前
    需求都没掰扯清楚就让你开工干活,然后交付的时候 各种返工,

    你不会想要这种的。。。
    lzeeee
        66
    lzeeee  
       43 天前 via iPhone
    总比上线之前改 prd 更舒服吧,你懂的
    EndlessMemory
        67
    EndlessMemory  
       43 天前
    要么加入,要么不加入
    xFrye
        68
    xFrye  
       43 天前
    挺好的,团队如果一直都坚持这样维护文档,以后要是某个人走了去改他的代码你也会轻松点
    woodfizky
        69
    woodfizky  
       43 天前
    你这是身在福中不知福啊。。你领导说的没毛病啊。。


    我领导的需求常常是,一两句模糊的话,没有文档。需要产品经理和开发自己去琢磨提炼原始需求。

    时常出现领导太慢,需求太模糊,然后产品经理或者开发自己理解错误,准备验收的时候发现理解错误,返工还好,就怕颠覆原始设计。
    woodfizky
        70
    woodfizky  
       43 天前
    @woodfizky 69
    typo: 领导太忙*
    C3WC
        71
    C3WC  
       43 天前
    op 标题是不是有错别字?
    xz410236056
        72
    xz410236056  
       43 天前
    GPT 不就是做这些工作的???你把你想到的简单跟 GPT 写一下,让他帮你出个详设文档,你再稍微改一下,节约大量时间
    abelmakihara
        73
    abelmakihara  
       43 天前
    这是日企还是做对日出来的吧
    理想是好的但实际上...
    hafuhafu
        74
    hafuhafu  
       43 天前
    时间给够就行,而且这反而很好生成对应的文字啊...
    nenseso
        75
    nenseso  
       43 天前
    我感觉对于我这种边写边想的人很苦恼,我是属于前期大致画一下思维导图流程图,然后开始写,后面发现更好的设计会把前面推了重做,如果要我一开始写好文档开始搞,后面重新又要写文档
    chevalier
        76
    chevalier  
       43 天前
    "写代码为低级工作,确定业务为高级工作"

    我工作十年了,现在觉得你领导这句话是对的。公司是业务驱动的,写代码是最基础的事情。
    xiangbohua
        77
    xiangbohua  
       43 天前
    "写代码为低级工作,确定业务为高级工作"
    这句话很对,你领导应该是经历过的人。而且这样很好,有利于习惯养成,如果野惯了以后想提高就很难了,如果领导时间评估合理,并且会给予指导的话,那这领导妥妥的跟着啊。
    xiangbohua
        78
    xiangbohua  
       43 天前
    @locoz 非常认同,我觉得不说单纯的 CRUD 了,即使是复杂的功能,如果不是自己设计的那么本身就确实比较初级。会写代码的人太多了,如果能快速准确的理解业务、然后根据经验快速给出扩展性良好、可行性高的方案的人就比较吃香了。
    repus911
        79
    repus911  
       42 天前
    只要把写文档加入排期和时间规划,我是赞成写好点和有标准,并随版本维护的,只是我给下面发任务会这么干
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1462 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 72ms · UTC 17:12 · PVG 01:12 · LAX 10:12 · JFK 13:12
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.