总体设计文档到底该写些什么? | 架构师之路(15)

科技   2024-11-28 08:10   北京  
《架构师之路:架构设计中的100个知识点》
15.总体设计文档

总体设计,是架构师经常要写的文档。


总体设计文档,一般要写些什么呢?

除了需求模块,技术的部分至少应该包含设计目标,系统架构,模块简介与设计折衷这四个部分。


需求模块一般怎么写?
可以用产品的语言描述需求,怕麻烦的话,也可以拷贝需求文档的链接。

设计目标模块一般怎么写?
设计目标又分为功能目标与性能目标:
(1)功能目标,是对产品需求的技术描述;
(2)性能目标,是根据业务数据对系统性能进行的评估;

性能目标非常重要,它很可能会影响整个设计方案。

系统架构与模块简介一般怎么写?
(1)系统架构,一般会画一个架构图,并配以文字对架构进行简要说明;
(2)模块简介嘛,是对架构图中多个模块的说明介绍;

总体设计文档中,哪个模块最为重要?
设计折衷这个模块最为重要

为什么设计折衷最为重要呢?
总体设计文档撰写完之后,要进行总体设计评审。总体设计评审的内容主要就是方案的设计折衷,讨论各个方案的优缺点,并确认最终使用哪种方案

因此,总体设计文档里一定要说明,多个方案的优缺点,以供设计评审时讨论。如果设计文档里只有一种方案,那设计评审的意义便不大了,会演变为评审委员会帮助架构师思考方案的不足,以及临时提供解决方案。

另外,在总体设计评审过后,也一定要更新文档,说明最终使用了哪种方案,以及为什么使用这种方案有时候因为排期或者其他原因,不一定采用了最优的设计方案,此时更应该在文档中记录决策的过程与原因。

如果不记录,别人拿到你设计的系统,设计方案可能完全就是个谜。

另外,设计折衷是架构师进行自我辩解的最佳机会:因为项目进度,因为历史遗留问题,我不得不采取了这样一坨设计方案,情有可原,以后不要再骂我了。

简单总结:
(1)总体设计文档,一般包含需求、设计目标、系统架构、模块介绍、设计折衷这5个部分;
(2)其中最重要的,是设计折衷。

知其然,知其所以然。
思路比结论更重要。

补充阅读材料:
《如何写好系统设计文档》
https://www.freecodecamp.org/news/how-to-write-a-good-software-design-document-66fcf019569c/

1. 设计文档要包含哪些内容?
- 需求背景与上下文说明
- 设计目标与里程碑
- 潜在方案与设计折衷
- 测试,监控,告警方案
2. 怎么写设计文档?
- 简洁
- 架构图,表格,数字
- 试着搞笑一点

文章不长,10分钟搞定。

==全文完==


20年,系列1:
流量从10万到10亿,遇见的80个架构问题(8000字长文)》
以实践为主线,结合讲解架构知识点几十个小时视频内容,已完结

今年,系列3:
《架构设计中的100个知识点》
架构知识点为主线,结合讲实践。讲解形式:短视频+图文+直播+星球社群,免费欢迎感兴趣的童鞋关注。
架构师究竟应该具备哪6项技能?

置顶标星日更好文不错过。
若有收获,点赞,转发,在看三连。感谢!

架构师之路
架构师之路,坚持撰写接地气的架构文章
 最新文章