一起养成写作习惯！这是我参与「掘金日新计划 · 4 月更文挑战」的第5天，点击查看活动详情。
无奈的现实
作为服务端开发，对于中小型的需求（比如只涉及单端 <5人天）出技术方案常让人苦恼，费时间，费力，时不时还要务虚一下，说句大白话，有那点时间，代码早都写完了，何必呢？
往粗了写，主要是给 leader 看，要讲「政治正确」，起不到实际帮助自己理顺 todo 的效果。
往细了写，业务代码细节多，能看懂的人，其实基本不需要看，本来也知道要怎么做。
但常常我们又不得不写一个技术方案出来，从项目推进的「政治正确」，到 leader 的要求，到很多项目的复盘todo，很可能强制你必须整个文档出来。
作为服务端一线研发，我们应该怎样看待「技术文档」，又该怎么去写呢？
为什么要有方案文档
- 以较为系统化的方式，梳理清楚要做的事情；
- 与合作者对齐上下文，保证对接人的认知一致；
- 明确方案的细节，提前暴露可能的风险和工作量；
- 记录自己的思考，以及项目执行中踩过的坑，方便之后回过头来 review ，排查问题；
- 让 leader 了解你的思考和设计，作为绩效的证明；
- 帮助其他同学了解业务，为未来可能的交接做好准备。
一篇优质的技术方案文档，可以帮助你省下大量的沟通成本，也可以提前规避掉潜在的风险，带来的杠杆效应其实是很强的。也因为你需要出一个技术文档，很多一拍脑门就定下来的设计会被二次 review，修正不合理的部分。
那么，究竟是什么在阻碍我们认真把自己的方案，产出为一篇技术文档呢？
阻力一：被挤压的方案设计时间
你所在的业务，一个需求从产品提出，到上线，需要几天？假设我们也来排一个 pct99，这个时间能控制在一个合理范围么？
国内互联网超高速的迭代环境，使得很多情况下，留给「技术方案设计」的时间少之又少，一个合理的流程是：
- 产品提出需求;
- RD 评审，确定需求合理性，可行性;
- RD 技术方案设计;
- 各端研发和 QA 给出预估排期；
- 进入开发；
- 联调；
- 测试；
- 产品验收；
- 客户端发版 / 服务端上线。
现实情况是，很多时候在第二步「研发评审」之后，在一两天之内就需要给出排期（几个小时甚至要求当场给的也不算罕见）。第三步「RD 技术方案设计」的意义和耗时被很大程度上忽视了。
事实上，哪怕不谈规模较大的需求，仅仅是单端5人天的规模，也需要研发对历史工程以及代码逻辑实现充分理解，对于复杂的业务，还需要考虑不同模块的边界，不同方案的长期影响。忽略「技术方案设计」排期的重要性，只会导致 RD 匆匆拍脑门定方案，为业务长期的稳定性埋坑。
这里并不是说所有需求都需要很长时间来设计，而是需要对「技术方案设计」产生的人力以及时间消耗，有足够的意识和尊重。
作为后端研发，这也是我们需要尽可能守住的底线，用正确的方式做事，不要太轻易的妥协。如果确实没有思考清楚，需要进一步梳理方案，就明确抛出自己的 concern，要求技术设计的时间，而不是轻易承诺一个排期。
阻力二：非正常的排期
倒排，leader指定排期，卷出来的激进排期，这些在目前互联网环境下并不罕见。一旦你因为这些种种原因，给了一个很激进的排期，就会出现连锁反应。
担心开发不完 => 不写技术方案 => 遇到问题，边开发边修正 => 出现遗漏/问题 => 质量无法保证，后续上下文缺失
其实回过头来看，真的有那么多非上不可，紧急到不能行的需求么？
阻力三：对效率的阻碍
软件工程的一个突出的难点就在于现实和理想之间巨大的鸿沟，你希望自己的工程是 Clean Arch，DDD，单测覆盖率100% 的模范，可现实往往是接手别人的烂摊子。改不动，也承担着巨大风险。
我见过一些能写出很优秀的技术文档的同事，很多时候也对写技术设计很抗拒，除非真的是规模比较大的项目。原因也很简单，即便能够写出一篇很好的设计，也免不了公开评审，被 leader 或其他可能并不了解具体情况的高阶同事质疑，进而就需要二次，三次改文档，重新review。
如果你记性很好，业务稳定，经验丰富，认真产出一篇技术设计文档的意义的确会降低。再三修改文档重新 review 的过程中，损失了大量开发时间，但你的项目很多时候并不会因此而延后。辛辛苦苦写出来了文档，一旦被打回，就意味着又少了很多开发时间。何必呢？
阻力四：自己偷懒
坦率的讲写一篇技术文档是一件不容易的事，尤其是对一些原则没有很好意识的研发更是如此。
你需要去充分思考，需求的意义，需求的边界，竞品的对比，去寻找最佳的解决问题的办法。而这，是需要花费思考和精力的。
草草提出来一个idea就去执行，远比思考交流后产出设计要来的简单的多。眼前的事情搞定就行，何必跟自己过不去呢。这种想法就是问题的根源。
面对阻力，我们应该怎么办
- 让技术文档成为你的帮手，而不是累赘；
- 主动地学习和思考，克制惰性；
- 守住自己的底线，不随意妥协。
设计原则
- Helpful
每篇文档最重要的读者一定是研发自己，通过思考和梳理，明确需求的实现方式，让下一步的todo更清晰，想清楚事情，这是技术文档最核心的目标。如果洋洋洒洒，各种抽象设计，华丽图表，项目意义一大堆，却无法实际帮助到技术落地，这样的设计是浪费生命。同样的，如果项目明明非常简单，为了给别人看而东拉西扯硬要整个文档，亦是如此。
- Concise and on point
方案的存在，不是为了充字数，一定要保证精练，务实，不说废话，切忌炫技。
- Think it through
不经过深入思考的方案是无意义的。这里需要我们克服惰性，全面地思考方案。因为有一个方案要设计，我们才会来思考关键的问题。比如：
- 为什么要做这件事？
- 这件事意义有多大，在整体项目里程碑里位于什么位置？
- 这件事的落地目标是什么？
- 现有业务为什么不支持，有没有问题；
- 竞品分析.
有必要的话，可以拆出来「概要设计」「细化设计」两个文档，前者侧重整体架构，宏观的交互，后者侧重于技术方案落地的细节。
示例结构
这里给出一个示例的文档结构，可以根据实际业务情况添加或修改：
- 名词解释
- 项目背景
- 设计目标
- 业务模型
- 整体架构
- 具体模块设计
- 存储设计
- 灰度，上线方案（老版本怎么办，如何兜底）
- 强弱依赖分析，如何降级
- 异常case的处理方式
- 性能评估（容量够不够，能不能抗住线上流量）
- 系统监控，业务监控，报警
- 如何衡量产出（指标？新的产品能力？）
执行后阶段
这一点很多人会漏，但我觉得很有必要，一线研发经常遇到这些问题：
- 很多方案和最后落地不一样，后人只看文档，不知道到底发生了什么；
- 方案有微调，未体现在设计上；
- 一些关键决策，停留在了IM 和口头交流，没有形成文字记录，导致后人再把坑踩一遍。
这个阶段，是执行过程中和执行完成后要补充的，包括：
- 核心问题解决思路，如果有相关业务同学的讨论，核心立场是什么，怎么看待；
- 最后执行的方案；
- 做的过程中遇到的问题，后续应该怎么调整和进一步改进。
无论是在设计文档中新建一节记录，还是直接更新到原有目录里皆可。重要的是，让你的讨论，执行的关键节点和结论都体现在文档里。