码迷,mamicode.com
首页 > 其他好文 > 详细

别人不写设计文档,我写了,所以我吃亏了?

时间:2020-11-10 11:29:18      阅读:10      评论:0      收藏:0      [点我收藏+]

标签:参数   uid   mic   原因   工位   简单的   相关   有用   编码   

《如何写技术文档?》的评论让人感到意外,一篇关于“如何写好设计文档”的文章,评论里充斥着各种戾气。

不确定自己的理念,在互联网新时代,是否已经过时,似乎写文档成了少数派。无论如何,旗帜鲜明的表达一下自己的看法。

本文所有观点均为个人观点,不存在任何“评判”,分享自己认为正确的观点。
画外音:后文中的素材,截图自《如何写技术文档?》的评论,隐去了头像和名称。

一、
技术图片
《如何写技术文档?》评论里,点赞最多的观点是:不写技术文档,是因为只有这样,老板才不敢随便替换ta,让ta具备“不可替代性”。

然而,“职场不可替代性”
不是指:
“我埋了很多隐藏坑,只有我知道隐藏坑在哪里,所以我不可替代”。

而是指:
“我具备其他人不具备的核心竞争力,可能是态度,可能是专业能力,也可能是长得帅”。

阳光正能量:

在职场冥思苦想,通过“挖坑”来保住自己的“铁饭碗”,不如努力提升自己的核心竞争力,让自己具备到哪里都有饭吃的能力。

二、
技术图片
第二类观点是:文档是写给别人看的,给老板,给客户,给要沟通的人,要接手项目的人。项目参与者本身不需要写文档。

为什么要写设计文档?

对自己,让自己在动手写代码之前,帮助自己想得更清楚;
对项目,保证信息的一致性,保证项目的可控性,减少项目风险;
对团队,确保知识的沉淀与传承;

项目涉及多少个子系统,每个子系统涉及多少个模块,模块间的依赖关系如何,彼此要提供多少个接口,每个接口的参数如何,接口实现过程中上下游交互如何,核心逻辑用什么技术方案实现… 难道相关技术人都一清二楚么?

很多自信的技术大神,“以为”懂了,但却讲不明白,其实就是不懂。
很多“讲得明白”,却“写不清楚”,其实就是没懂透。
把一个项目,一个技术问题,按照逻辑,用文字来一遍,才表示真正的想清楚了。
画外音:落地到纸面,能发现设计中的很多问题。

文档如何保证信息的一致性,减少项目风险?

举个简单的例子,PHP工程师要提供一个获取订单信息的HTTP接口,后期要与IOS/Android/FE工程师联调,同时QA工程师也需要测试。

难道不需要把HTTP接口落地到纸面么?

http://daojia.com/order/getinfo?oid=${oid}
cookie: uid=${uid}
cookie: token=${token}

RESTFUL接口格式,输入输出格式,这些信息是PHP/IOS/Android/FE/QA工程师们都需要明确的信息,否则相关研发联调测试工作就无法展开,这些信息,难道每次都需要口头沟通么?

项目上线1年后,接口要迭代升级,难道每次都需要去代码里查么?
画外音:注释很重要,注释与文档并不冲突,它们解决的并非同一个问题。

阳光正能量:

写好文档对自己,对项目,对团队都是有好处,何乐而不为呢?

三、
技术图片
第三类观点是:没有时间写。

上帝是公平的,时间是守恒的,多花一些时间想清楚设计,编码一定能更顺畅,能够减少很多沟通/扯皮的时间,能够节省很多方案变更导致的额外的修改/联调/测试的时间,能够节省很多中长期维护的时间。

阳光正能量:

我想健身,但我没有时间。
我想学英语,但我没有时间。
我想写好文档,但我也没有时间。
刷朋友圈,刷头条,刷抖音,追连续剧,我有时间。
拒绝借口,一起行动起来,写好技术文档。

四、
技术图片
还有一类观点:需求变化快,方案变化快,文档写得慢,于是,写文档没有用。

讨论一个事情,先讨论合理性,如果合理,但是有困难,再看有困难的解决方案,正常应该是这样的一个逻辑,对吧?

因为:
“需求变化快,方案变化快,文档写得慢”
所以:
“写文档没有用”
这个逻辑本身就是错的。

我们(特别是有话语权,决策权的技术leader)首先,难道不是应该想一想:

  • 需求总是变,是否合理?
  • 方案总是变,是否合理?
  • 文档写得慢,是否合理?
  • 没有文档,是否合理?
    难道不是应该先问自己这些问题么。

如果认为“文档写得慢不合理”,接下来,难道不是应该想一想:
为什么写得慢,是员工意愿不足,员工能力不足,工具不好用,还是其他原因?

  • 如果意愿不足,如何提升员工意愿
  • 如果能力不足,如何提升员工能力
  • 如果工具不好,如何优化工具效率

存在未必合理:

  • “奴隶制度”存在了几千年,所以生之为奴就合理么?
  • “需求总变,方案总变,没有文档”,但这些就一定合理么?

阳光正能量:

作为技术leader,你团队里的兄弟姐妹们在水深火热之中,你却不作为,你不愧疚么?请在自己能力范围内行动起来,去尝试改变不合理的现状,把技术氛围搞起来。

五、
技术图片
一类观点:别人不写,自己写,亏了。
技术图片

一类观点:老板需要文档,码农不需要。

技术图片

一类观点:工资这么低,不写;涨工资,才写。

技术图片

一类观点:写文档是成就别人。
画外音:评论太多,就不一一放出了,大家直接查阅《如何写技术文档?》底部评论吧。

一篇《如何写技术文档?》,在评论里大部分的观点是“写了没用”,这是我万万没有想到。
画外音:希望大家只是戏谑我,而不是真这么认为。

甚至,我会想,我一直坚持的东西,是对的吗?

2011年转岗,我认真做过一个“模块交接”,对当时负责的13个模块做了梳理和汇总,害怕自己转岗后,接手的工程师搞不定,而影响项目和模块,这样我会万分内疚。

技术图片
技术图片
技术图片
技术图片
甚至,在转岗几个月后,接手我模块的同事有疑问,我都会跑到同事工位,解答同事的问题。

结尾:

不管别人写不写文档,我觉得这是一件正确的事情,我就会去做。
不管别的leader要不要求写文档,在我的团队,我就会这么要求。

多年以后,或许你会发现,正是因为你做了和别人不一样的选择,你成了和别人不一样的你。

共勉!

技术图片
架构师之路-分享可落地技术

相关推荐:

《如何写技术文档?》
《需求总是变,合理吗?》
技术图片

调研:

对于不合理的事情,你的老板是否有作为?

别人不写设计文档,我写了,所以我吃亏了?

标签:参数   uid   mic   原因   工位   简单的   相关   有用   编码   

原文地址:https://blog.51cto.com/jyjstack/2548565

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!