聊聊后端技术文档那些事

·  阅读 1010

一起养成写作习惯!这是我参与「掘金日新计划 · 4 月更文挑战」的第5天,点击查看活动详情

无奈的现实

作为服务端开发,对于中小型的需求(比如只涉及单端 <5人天)出技术方案常让人苦恼,费时间,费力,时不时还要务虚一下,说句大白话,有那点时间,代码早都写完了,何必呢?

往粗了写,主要是给 leader 看,要讲「政治正确」,起不到实际帮助自己理顺 todo 的效果。

往细了写,业务代码细节多,能看懂的人,其实基本不需要看,本来也知道要怎么做。

但常常我们又不得不写一个技术方案出来,从项目推进的「政治正确」,到 leader 的要求,到很多项目的复盘todo,很可能强制你必须整个文档出来。

作为服务端一线研发,我们应该怎样看待「技术文档」,又该怎么去写呢?

为什么要有方案文档

  • 以较为系统化的方式,梳理清楚要做的事情;
  • 与合作者对齐上下文,保证对接人的认知一致;
  • 明确方案的细节,提前暴露可能的风险和工作量;
  • 记录自己的思考,以及项目执行中踩过的坑,方便之后回过头来 review ,排查问题;
  • 让 leader 了解你的思考和设计,作为绩效的证明;
  • 帮助其他同学了解业务,为未来可能的交接做好准备。

一篇优质的技术方案文档,可以帮助你省下大量的沟通成本,也可以提前规避掉潜在的风险,带来的杠杆效应其实是很强的。也因为你需要出一个技术文档,很多一拍脑门就定下来的设计会被二次 review,修正不合理的部分。

那么,究竟是什么在阻碍我们认真把自己的方案,产出为一篇技术文档呢?

阻力一:被挤压的方案设计时间

你所在的业务,一个需求从产品提出,到上线,需要几天?假设我们也来排一个 pct99,这个时间能控制在一个合理范围么?

国内互联网超高速的迭代环境,使得很多情况下,留给「技术方案设计」的时间少之又少,一个合理的流程是:

  1. 产品提出需求;
  2. RD 评审,确定需求合理性,可行性;
  3. RD 技术方案设计;
  4. 各端研发和 QA 给出预估排期;
  5. 进入开发;
  6. 联调;
  7. 测试;
  8. 产品验收;
  9. 客户端发版 / 服务端上线。

现实情况是,很多时候在第二步「研发评审」之后,在一两天之内就需要给出排期(几个小时甚至要求当场给的也不算罕见)。第三步「RD 技术方案设计」的意义和耗时被很大程度上忽视了。

事实上,哪怕不谈规模较大的需求,仅仅是单端5人天的规模,也需要研发对历史工程以及代码逻辑实现充分理解,对于复杂的业务,还需要考虑不同模块的边界,不同方案的长期影响。忽略「技术方案设计」排期的重要性,只会导致 RD 匆匆拍脑门定方案,为业务长期的稳定性埋坑。

这里并不是说所有需求都需要很长时间来设计,而是需要对「技术方案设计」产生的人力以及时间消耗,有足够的意识和尊重。

作为后端研发,这也是我们需要尽可能守住的底线,用正确的方式做事,不要太轻易的妥协。如果确实没有思考清楚,需要进一步梳理方案,就明确抛出自己的 concern,要求技术设计的时间,而不是轻易承诺一个排期。

阻力二:非正常的排期

倒排,leader指定排期,卷出来的激进排期,这些在目前互联网环境下并不罕见。一旦你因为这些种种原因,给了一个很激进的排期,就会出现连锁反应。

担心开发不完 => 不写技术方案 => 遇到问题,边开发边修正 => 出现遗漏/问题 => 质量无法保证,后续上下文缺失

其实回过头来看,真的有那么多非上不可,紧急到不能行的需求么?

阻力三:对效率的阻碍

软件工程的一个突出的难点就在于现实和理想之间巨大的鸿沟,你希望自己的工程是 Clean Arch,DDD,单测覆盖率100% 的模范,可现实往往是接手别人的烂摊子。改不动,也承担着巨大风险。

我见过一些能写出很优秀的技术文档的同事,很多时候也对写技术设计很抗拒,除非真的是规模比较大的项目。原因也很简单,即便能够写出一篇很好的设计,也免不了公开评审,被 leader 或其他可能并不了解具体情况的高阶同事质疑,进而就需要二次,三次改文档,重新review。

如果你记性很好,业务稳定,经验丰富,认真产出一篇技术设计文档的意义的确会降低。再三修改文档重新 review 的过程中,损失了大量开发时间,但你的项目很多时候并不会因此而延后。辛辛苦苦写出来了文档,一旦被打回,就意味着又少了很多开发时间。何必呢?

阻力四:自己偷懒

坦率的讲写一篇技术文档是一件不容易的事,尤其是对一些原则没有很好意识的研发更是如此。

你需要去充分思考,需求的意义,需求的边界,竞品的对比,去寻找最佳的解决问题的办法。而这,是需要花费思考和精力的。

草草提出来一个idea就去执行,远比思考交流后产出设计要来的简单的多。眼前的事情搞定就行,何必跟自己过不去呢。这种想法就是问题的根源。

面对阻力,我们应该怎么办

  • 让技术文档成为你的帮手,而不是累赘;
  • 主动地学习和思考,克制惰性;
  • 守住自己的底线,不随意妥协。

设计原则

  • Helpful 每篇文档最重要的读者一定是研发自己,通过思考和梳理,明确需求的实现方式,让下一步的todo更清晰,想清楚事情,这是技术文档最核心的目标。如果洋洋洒洒,各种抽象设计,华丽图表,项目意义一大堆,却无法实际帮助到技术落地,这样的设计是浪费生命。同样的,如果项目明明非常简单,为了给别人看而东拉西扯硬要整个文档,亦是如此。

  • Concise and on point 方案的存在,不是为了充字数,一定要保证精练,务实,不说废话,切忌炫技。

  • Think it through 不经过深入思考的方案是无意义的。这里需要我们克服惰性,全面地思考方案。因为有一个方案要设计,我们才会来思考关键的问题。比如:

  1. 为什么要做这件事?
  2. 这件事意义有多大,在整体项目里程碑里位于什么位置?
  3. 这件事的落地目标是什么?
  4. 现有业务为什么不支持,有没有问题;
  5. 竞品分析.

有必要的话,可以拆出来「概要设计」「细化设计」两个文档,前者侧重整体架构,宏观的交互,后者侧重于技术方案落地的细节。

示例结构

这里给出一个示例的文档结构,可以根据实际业务情况添加或修改:

  1. 名词解释
  2. 项目背景
  3. 设计目标
  4. 业务模型
  5. 整体架构
  6. 具体模块设计
  7. 存储设计
  8. 灰度,上线方案(老版本怎么办,如何兜底)
  9. 强弱依赖分析,如何降级
  10. 异常case的处理方式
  11. 性能评估(容量够不够,能不能抗住线上流量)
  12. 系统监控,业务监控,报警
  13. 如何衡量产出(指标?新的产品能力?)

执行后阶段

这一点很多人会漏,但我觉得很有必要,一线研发经常遇到这些问题:

  1. 很多方案和最后落地不一样,后人只看文档,不知道到底发生了什么;
  2. 方案有微调,未体现在设计上;
  3. 一些关键决策,停留在了IM 和口头交流,没有形成文字记录,导致后人再把坑踩一遍。

这个阶段,是执行过程中和执行完成后要补充的,包括:

  • 核心问题解决思路,如果有相关业务同学的讨论,核心立场是什么,怎么看待;
  • 最后执行的方案;
  • 做的过程中遇到的问题,后续应该怎么调整和进一步改进。

无论是在设计文档中新建一节记录,还是直接更新到原有目录里皆可。重要的是,让你的讨论,执行的关键节点和结论都体现在文档里。

分类:
后端
标签:
收藏成功!
已添加到「」, 点击更改