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

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

  •  
  •   Vaspike · 2024-05-29 11:36:33 +08:00 · 9242 次点击
    这是一个创建于 368 天前的主题,其中的信息可能已经有所发展或是发生改变。
    • 矛盾

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

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

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

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

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

    第 1 条附言  ·  2024-05-30 04:07:44 +08:00

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    怎么说呢

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

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

    "写代码为低级工作,确定业务为高级工作" 个人觉得这个没啥毛病吧,前提是能真的确定好
    encro
        28
    encro  
       2024-05-29 13:49:13 +08:00
    先设计再编码!

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


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

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

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

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

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

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

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

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

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

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


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

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

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