技术详设文档化的重要性

Posted 2021-11-22 amongdata

优秀详设能达到的效果

让未全程参加项目、甚至完全不了解项目的干系人通过文档能完整的了解整个事件（项目），包括：事件的前因（背景）后果（目标）--问题域；准备怎么做，为了表述清楚怎么做，通常会按技术相关维度度展开（解决方案域）；配合该解决方案，可能会存在什么样的问题或风险。

详设的现实意义

1.为了我们自己

减少无用功

详设要求我们做之前想清楚，需要清楚的内容包括：

a. 问题空间（需求）想清楚。从用户、产品角度去思考，要比产品考虑的更多多，才有能力拒绝需求（拒绝需求也是一种重要能力）。会不会有同学觉得产品提的需求就这样，出了问题也不管我的事？no, no, no, 关老大的事了，没人想自己累死累活做的项目最后被删除代码，丢掉吧？如果开始的需求就不合理，或者对用户价值很低，那我们的代码注定是吃土的命运，我们的付出也将毫无意义

b. 解决方案（详设）想清楚。事前想清楚是对我们能力的一个要求，是面向接口设计的具体落体能力的体现。试想，事前想不清楚会有什么后果？做到一半发现这里不对，有点问题，需要从新弄一下；再做做，哎，好像那里也有点问题。于是边搞边想，边想边搞。最后时间来不及了，打补丁吧，以后难搞的事先管不了啦。画面是不是很熟悉。所以设计阶段想清楚了，实现只是一次性码砖而已，码砖时间是占整个研发时间最少的，大头都给设计评审阶段了。大厂都这么干，不然哪里能挤出20%的创新时间。

• 反向：没想清楚的后果：整个项目无用功；代码里面设计混乱，实现混乱，难维护，后期难改。自己痛苦，接手别人项目更痛苦
• 正向：锻炼我们的事前设计能力，推演能力，表达能力；评审会是一个技术交流的平台，是参会者一起帮设计者完善他的思考完整度和全面性的场合

     设计者（架构师）要追求的更高要求：

• 能将简单的事想复杂，为了控制风险和准备未来
• 能将复杂的事做简单，为了控制成本和做好产品
• 能将复杂的事讲（写）简单，为了更好的传承和成长（教学相长）

2.为了传承

详设文档是对专业技能的传承，也是对业务的传承

详设写作的过程是验证我们所思，也是提炼思想的过程，是对成长最有助益的阶段，教学相长，能快速促进认知的提高。

详设评审是一个技术交流的过程，各抒己见，通过他人（尤其是经验丰富的同学）的补充来完善设计，对技术设计思路进行交流，促进设计者反思提升。这是一种技能的传递，团队内的互助，由老人传递给新人，新人再反馈给老人。

最后产出的设计文档也是业务的传承。你团队有新同学来吧，怎么让他快速了解业务；团队有老同学走吧，怎么能对重要业务没有遗漏的交接；你想重构别人代码了，怎么知道以前的逻辑；还有，还有，产品与产品的交接，技术与技术的交接，产品与技术的新老对接的流动，最后谁能说清楚老功能的来龙去脉呢？详设文档