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

[Vaspike]

• 矛盾

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

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

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

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

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

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

[zhwq]

就当锻炼自己的文档能力了，后续对你帮助很大的。

[chaoschick]

没有什么是不能习惯的

[Meteora626]

写代码为低级工作,确定业务为高级工作 这句话没毛病，但是只要确定输入输出有啥就行了，写内部细节也太离谱了

[Mithril]

他的看法在大部分公司都是对的，毕竟造火箭的公司不多，CURD 能不能卖钱还是要靠业务。

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

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

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

都搞定了就可以准备跳槽了。这次再跳至少不会说什么 “公司技术栈陈旧，没有学习机会” 了。

[locoz]

有一说一，没太大问题...写业务代码就是低级工作，根据业务进行设计才是高级工作，只会写业务代码屁用没有。
先写文档还是先写代码就是个风格、习惯的问题，各有优劣。但是在当下，先写一份设计清晰、描述详细的文档，是可以让 AI 快速解决代码的问题的，只要你的文档足够明确，AI 生成的代码跟你直接写的没区别，甚至可能更好，而且在整理思路上还会更优于边写代码边改。

[beimenjun]

简明版：按照你的领导说的做

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

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

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

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

整体来说，按照你这个描述，我觉得你如果想吐槽，可能只是不适应。建议好好适应。

[TWorldIsNButThis]

日企出身？

[LawlietZ]

和你有类似经历，之前老板也是对文档要求很高，语句通不通顺都有要求，画图要求都很高，一个文档能改十几遍，确实难受，但确实也有提升，这种情况确实会导致下面员工离职率不低，只能说好好沟通面向老板输出吧，保证写文档时间够和薪资不错就行了

[wu00]

“写代码前要求我先把文档写出来,详实程度要求每个 service 中将会有哪些方法,共有私有”只有少部分优秀的开发有这个能力

[haliluya]

经历过这么多年，很赞同“写代码为低级工作,确定业务为高级工作”这句话。代码实现，随便找个两三年工作经验的，基本上都可以胜任（普通功能需求，无高深逻辑算法，不犟）。但是如果找一个对业务很熟悉，一聊就明白的，很难，码农在一个公司长久的优势基本上就是业务理解了吧...个人偏见，不喜随便喷

[smdbh]

给时间照做就行了
开始阶段，我觉得写文档和写代码都是一种设计结构的方法，写出来才能发现问题，逐步修改。这是管理者只愿意看图流程图之类的文档而已，没心思看代码。 除非是成熟项目，不然一次成型的概率太低了，最后还不是都要改

[watzds]

@Mithril #4 以前数据库语句都要给 DBA 审核，我就是这样先写代码，再自动提取哈哈，文档写这些东西繁琐了

[heyjei]

"写代码为低级工作,确定业务为高级工作" 这句话没毛病。 业务代码最不值钱了，其包含的业务知识才值钱。

[Mithril]

@watzds 对的，所以其实工作是死的，但人是活的。

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

反正工作就是那些，自己找点乐趣好了。

[darkengine]

这个是很自然的流程啊，只不过有些步骤之前是在脑子里过一遍，现在是要你写下来而已。

[cmsyh29]

你领导说的没错

[nomytwins]

往往写代码的不这么认为"写代码为低级工作,确定业务为高级工作"。尤其是后端。

[murmur]

哦，这不就是日式开发吗

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

怎么说呢

const six = 6 //66666666

[guanzhangzhang]

找一些框架按照代码生成文档，还能根据代码 tag 做版本管理😏

[azarasi]

可以用 doxygen 生成 xml 格式的文档，然后自己写一个程序解析生成领导要求的格式

[Tyrant1984]

还行吧，我这边 SB 公司，写个周报老板甚至会挑你标点符号用的不够“标准”，比如分段数字序号后面必须用顿号，分段结束后必须用分号之类的，标点符号不能让他满意他就让你重写。

[anzu]

业务驱动型项目是这样的。日企项目的文档才是详细到令人震惊，连方法内的代码也会在文档中以伪代码的形式描述出来。

[7lQM1uTy635LOmbu]

@Tyrant1984 #21 像极了我曾经做过的文档工程师

[huang86041]

和日企打过交道，很像日企的风格。

[NessajCN]

论 Rust 的优越性...
懂不懂 cargo doc 能省多少事啊....

[kneo]

私有方法是不可能在设计阶段就确定的。甚至公有接口也往往不能在设计阶段就能完全确定。在设计阶段纠结过多末枝细节是会降低生产力的。

当然，我有一个巧妙的方法，相信你也想到了。你先偷偷把代码写出来，然后作为设计提交上去。至于领导分配的写代码的时间，你可以去摸鱼，也可以提前去预测他下一阶段的设计。

[weofuh]

代码注释写详细点，再搞个工具，把注释提取出来就是文档了，哈哈哈哈。

"写代码为低级工作,确定业务为高级工作" 个人觉得这个没啥毛病吧，前提是能真的确定好

[encro]

先设计再编码！

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


我就是这么训练自己和 chatgpt 的。
先自己写伪代码，注释，然后将写代码变为填空。
当我发现自己设计出错了，那么往往就又学到了。

[k9990009]

给时间就行。研究下那种类似 yapi 接口文档生成工具，将代码注释提取生成文档

[SoyaDokio]

感觉是个很好的锻炼机会。
业务万变不离其宗写来写去就那么些，唯有业务五花八门，理解稍有偏差就可能导致成果物相去甚远。

另外文档这个东西是非常重要的，代码写多了可能就渐渐理解了。

[Tink]

这些东西可以交给 gpt 来做

[kamilic]

其实挺好的，设计到位了，其实怎么实现都是差不多的样子

[silencil]

大部分业务没有做设计的必要吧？很多接口，脑子里一过就知道是怎么回事，留个文档就是方便后续的人维护，但是文档很容易跟不上代码变更，初始的文档很可能又废了。

[yangzzzzzz]

写呗 反正算工时就行

[F7TsdQL45E0jmoiG]

这详实程度确实不够高

[NICEghost]

低级程序员，隐忍

[Motorola3]

工资待遇很不错就够了，毕竟他这个问题又不是什么十恶不赦的问题，只是有点吃屎，而且你为啥非要按照他的流程走，不能自己先写一部分然后用 AI 搞定文档自己再删删改改吗，我倒是认为你们老板的想法没啥大问题，确定业务就是很重要，毕竟你再花里胡哨的业务，只要是正常的基本都有人实现过了，代码层面都有可参考的东西，毕竟码农就是...

[Huelse]

你领导没错，代码只是低级工作，你甚至可以交给刚毕业的大学生写，但实现设计并不是谁都能做好。

等你写代码的时候更多考虑的是语法和语言特性，不会有太多思考逻辑的时间，这也是为什么要在开会和写文档的时候多思考，想好了再动手。

[mark2025]

抽象接口，方法用 swagger 加上输入输出备注，然后生成网页或者文档不行么？

[ShuWei]

既然钱给够了，你还有啥好抱怨的，如果你是给工资的人，你可以决定工作方式，否则做好执行

[aikilan]

你的领导是对的

[Akiya]

文档要多详细暂且不说，稍微工作过几年都应该知道需求确定的过程比实际开发难多了，尤其现在 AI 这么强，你把需求写完以后基本上代码逻辑都不怎么需要自己动手了

[royking930911]

编码本身就是耗时低级的工作 设计才是软件的核心 设计文档写的好 工程师可以直接把编码的工作丢给应届生或者 ai 完成

[4ark]

你觉得你应该庆幸你在这样的团队里面

[wanniwa]

按你说的，文档设计完了，基本上伪代码都写完了，照着思路改成代码很快的。

[dif]

工资待遇很不错，干啥都行。开会时间多，怕是没有主题吧。一开会就发散。东拉西扯得问题都要在会上解决。

[liyafe1997]

这算好了，如果你去搞汽车电子，很多情况下文档/流程这些乱七八糟的东西甚至占到工作量的 80%，甚至专门有一个团队去做这些，人比开发团队多。

[lshbosheth]

给时间 就行 这种是很正确的流程啊 0.0 正常就应该开会时间大于开发时间 开会就把如何实现与波及分析都做了 写代码不就是按部就班嘛

[orioleq]

需求以业务为主导的软件开发流程确实是这样，如果需求分析和系统设计做得清晰，后面开发和测试都省力。这一点会跟以技术为主导的快速 demo 的项目完全不一样。
如果是业务主导的开发 leader ，特别是只写思路代码交给小弟填充的，写设计文档这个能力是必须的吧。不然等代码都好了，再 review 再不断做 refactor ，又要搞好几轮，到时候挫败感更强。

[chanChristin]

@Tyrant1984 这种就适合 ChatGPT 润色

[iyaozhen]

核心矛盾: 工资待遇很不错
啥意思？工资给的高呗 那你还说啥

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

矛盾这个我说个事情，之前有个很大的 leader 说，如果我推行一个决策，都需要和每个人解释清楚，那事情就做不了了。所以很简单，如果你工作没几年就跟着 leader 走。如果你本身已经有一套方法论了，和 leader 不合拍那就换个团队。

[Seria]

只要不加班，那就是好的，只要加班，就算是再好的也是垃圾。

[yueyuea]

挺好的，我认为 coding 占用我们的工作时间应该不超过百分之 20 ，剩余时间都应该在反复的思考和沟通（当然还有摸鱼）。有效的沟通加文档可以减少很多无意义 coding 时间，比所谓的靠加班来完成工作的 leader 强的不是一星半点。

[weilongs]

同感,但我这个领导不是纯写代码,是一个网络方面的出身,写过代码. 他的想法就是写代码基本上有手+baidu 就行了. 也是让我写文档灰常细致,以及他要学习怎么启动、调试. 我觉得他这想法就是一直做我的备份.是在备份不了也要找一个好接手.

[ArrayBuffer]

认同领导的做法, 我觉得核心的问题是文档是否物尽其用, 文档的可读性好不好, 维护工作是否能做好, 能让别人看懂的文档才是有价值的

[hitmanx]

这个其实问题不大。是应该多花时间在设计上，设计阶段应该把所有的需求和未来的扩展性都考虑到，然后进行 review 。等到一切通过了，照着实现应该是很容易的。甚至设计和实现的可以不是同一个人。

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

但是国内的企业一半都是工期紧、任务重，很多东西都是没设计明白就键盘梭哈写代码了，回头再东改西改，这个其实是个坏的习惯。

[keakon]

你们没经历过重构么？
文档是不是也得重构啊？

[ZZITE]

@keakon #56 有啥问题，你都把代码重构了，文档不重写吗？这不就是坑对接的人

[horizon]

@Mithril #4
你这明显违背了初衷
要先写文档再写代码，而不是反过来

[keakon]

@ZZITE 什么项目对接要看文档里的私有方法？你代码里用 IDE 几秒钟就重构完了，然后点开几百篇文档去替换字符串么？

[yuankui]

现在 AI 这么多，根据代码生成文档不难吧？

[BraveChi]

1 、写文档要比写代码高级
2 、领导在锻炼你
3 、你干十年就知道了，去 tm 的写代码，还是写文档爽，谁干谁知道。文档可控，但是代码质量不可控啊。

[konakona]

不清楚你的领导是否被讲不清内容的功能代码弄烦了，但是向上管理和自我驱动应是每一位优秀的开发者的职业素养才对。

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

你领导的性格可能就是这样的，要么接受他一起勾着，要么另谋高俅换组换领导。

[doommm]

设计、接口文档可以写，私有的内部变量、方法这种涉及到实现细节的怎么事先写？设计的时候不能确定实现细节吧

[akira]

需求都没掰扯清楚就让你开工干活，然后交付的时候 各种返工，

你不会想要这种的。。。

[lzeeee]

总比上线之前改 prd 更舒服吧，你懂的

[EndlessMemory]

要么加入，要么不加入

[xFrye]

挺好的，团队如果一直都坚持这样维护文档，以后要是某个人走了去改他的代码你也会轻松点

[woodfizky]

你这是身在福中不知福啊。。你领导说的没毛病啊。。


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

时常出现领导太慢，需求太模糊，然后产品经理或者开发自己理解错误，准备验收的时候发现理解错误，返工还好，就怕颠覆原始设计。

[woodfizky]

@woodfizky 69
typo: 领导太忙*

[C3WC]

op 标题是不是有错别字？

[xz410236056]

GPT 不就是做这些工作的？？？你把你想到的简单跟 GPT 写一下，让他帮你出个详设文档，你再稍微改一下，节约大量时间

[abelmakihara]

这是日企还是做对日出来的吧
理想是好的但实际上...

[hafuhafu]

时间给够就行，而且这反而很好生成对应的文字啊...

[nenseso]

我感觉对于我这种边写边想的人很苦恼，我是属于前期大致画一下思维导图流程图，然后开始写，后面发现更好的设计会把前面推了重做，如果要我一开始写好文档开始搞，后面重新又要写文档

[chevalier]

"写代码为低级工作,确定业务为高级工作"

我工作十年了，现在觉得你领导这句话是对的。公司是业务驱动的，写代码是最基础的事情。

[xiangbohua]

"写代码为低级工作,确定业务为高级工作"
这句话很对，你领导应该是经历过的人。而且这样很好，有利于习惯养成，如果野惯了以后想提高就很难了，如果领导时间评估合理，并且会给予指导的话，那这领导妥妥的跟着啊。

[xiangbohua]

@locoz 非常认同，我觉得不说单纯的 CRUD 了，即使是复杂的功能，如果不是自己设计的那么本身就确实比较初级。会写代码的人太多了，如果能快速准确的理解业务、然后根据经验快速给出扩展性良好、可行性高的方案的人就比较吃香了。

[repus911]

只要把写文档加入排期和时间规划，我是赞成写好点和有标准，并随版本维护的，只是我给下面发任务会这么干