2024年Go最新如何编写好的软件设计文档_好的软件设计文档怎么写(1)，2024年最新华为大神花费5个月打造的这份714页学习笔记系列

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，涵盖了95%以上Go语言开发知识点，真正体系化！

由于文件比较多，这里只是将部分目录截图出来，全套包含大厂面经、学习笔记、源码讲义、实战项目、大纲路线、讲解视频，并且后续会持续更新

如果你需要这些资料，可以戳这里获取

已剪辑自: https://zhuanlan.zhihu.com/p/59533572

原文链接

作为一名软件工程师，我花了很多时间阅读和编写设计文档。在研究了数百篇这样的文档之后，我发现好的文档与项目成功之间有很强的关联性。

在本文中，我尝试去说明如何才能编写好的设计文档。

本文分为4个部分：

• 为什么要写设计文档
• 设计文档中应该包含哪些内容
• 如何编写
• 流程

为什么要写设计文档

设计文档 - 也被称作技术规范 - 描述了你计划如何去解决一个问题。已经有很多文章解释了编码之前编写设计文档的重要性。所以我在这儿要说的是:

设计文档是保证正确的工作得以完成的最有用的工具。

人们一般会认为设计文档是用来告诉别人系统是怎么工作的或者作为档案留存。设计文档确实可以起到这些作用，但这些并不是最主要目标。设计文档的最主要目标是推动你去思考，去收集反馈。

作为一般性原则，如果你工作的项目需要1个人月或者以上，就需要写设计文档。但其实对于更小型的项目，编写设计文档也是有益的。

我想如果您还在阅读，那么你一定是认可设计文档的重要性。但是不同的工程团队，甚至同一团队的工程师，经常以不同的方式编写设计文档。让我们来谈谈好的设计文档的内容，风格和流程。

设计文档中应该包含哪些内容

设计文档描述了针对一个问题的解决方案。既然问题是多种多样的，那么构建设计文档的方式也是不同的。

首先应该考虑在设计文当中包含以下几个部分。

标题和人员

设计文档的标题，作者（项目的参与者），文档的审阅者（我们将在后面的『流程』部分中详细讨论），以及文档最后更新的日期。

概述

可以被公司里任何一个工程师所理解并且根据概要内容决定是否需要阅读文档的其余部分。这部分最多不超过3个章节。

背景

对于问题的描述、为什么要做这个项目、评估项目需要了解哪些内容以及如何融入到技术战略，产品战略或者是团队的季度目标中。

目标和非目标

目标应该包括

• 描述项目对于用户的影响  — 这里的用户可以是其他团队或者系统
• 明确衡量目标的指标 — 如果可以通过一个仪表盘展示和跟踪这些指标就再好不过了

明确描述哪些问题不在目标范围内也同样重要。确保所有人对于目标的理解是一致的。

里程碑

一些可衡量的检核点。你的PM以及你的经理的经理通过浏览就可以了解项目各个部分的推进情况。如果项目超过1个月，我建议你把项目拆分成多个面向用户的里程碑。

使用自然日以便考虑延迟、假期和会议等等。它看起来可能是下面这个样子：

开始时间：2018年6月7日

里程碑1 - 新系统MVP可在夜间模式下运行：2018年6月28日

里程碑2 - 下线旧系统：2018年7月4日

结束日期：新系统增加功能X，Y，Z：2018年7月14日

如果其中一些里程碑的预计结束时间（ETA）发生变化，可在后面增加[更新]部分。这样项目干系人可以很容易了解到最新的计划。

现状

除了描述当前的系统实现以外，您还应该通过概要的流程图来描述用户是如何和系统交互以及数据是怎么流转的。用户故事是完成此类工作的很好的方式。但别忘了你的系统会有很多类型的用户，每种用户都有不同的用户用例。

建议方案

这是有些人称之为技术架构的部分。首先提供一个大的方向，然后填充大量的细节。尝试通过用户故事来进行细化。这部分可以包含很多内容和图表。想象你写完这部分就跑到一个荒岛上去度假了。团队里其他工程师可以轻松的通过这部分来实现这个方案。

替代方案

除了上面的建议方案以外，你还考虑过其他代替方案么？相比来说各有什么优缺点？有没有考虑过不是自己实现而是购买第三方解决方案或者是使用开源方案来解决问题？

可测试性、监控和报警

我喜欢在设计文档中包含这部分。人们往往会跳过这些工作，认为是最后才需要考虑的。但往往由于忽略了这些，出了问题以后，人们对问题为什么发生以及如何发生的一无所知。

跨团队的影响力

方案是否会增加值班人员和运维人员的工作负担？

方案成本是多少？

是否会引起系统回归的问题？

是否会引入新的安全风险？

有什么风险和副作用？

服务支持团队如何和客户沟通？

开放性问题

任何你有疑问，不完全确定的开放性问题，如你希望读者权衡的有争议的结论，后续完善的工作等等。也就是我们常说的『已知的未知』（Known Unknowns）

详细的范围和时间表

本节主要是为参与该项目的工程师以及他们的技术主管和经理准备的。所以这段放在文档的最后。

本质上来讲，这是你计划执行项目每一部分的分解。有很多内容是关于如何准确的界定范围，你可以阅读这篇文章了解更多关于范围界定的内容。

我倾向于用文档的这个章节来跟踪项目任务。每当范围的估算发生变化的时候，我就会更新这个章节。这个更多的是我个人的偏好。

如何编写

既然谈到了好的设计文档的内容，那我们就聊聊写作风格。我保证这个和你高中的英语课可不一样。

尽可能简单

不要写的像你读到的学术论文那样。那样写是为了取悦期刊的审核员。您的文档是为了描述您的解决方案并从其他团队成员那里获得反馈而编写的。你应该使用

• 简单的单词
• 简短的句子
• 各种列表
• 具体的例子，如『用户李磊链接到自己的银行账户，然后…』

尽可能使用图和图表

图比文字更容易阅读，图表往往用来比较几个可能的选项。我用Google Drawing来制作图表。

网上学习资料一大堆，但如果学到的知识不成体系，遇到问题时只是浅尝辄止，不再深入研究，那么很难做到真正的技术提升。

需要这份系统化的资料的朋友，可以添加戳这里获取

一个人可以走的很快，但一群人才能走的更远！不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！

知识不成体系，遇到问题时只是浅尝辄止，不再深入研究，那么很难做到真正的技术提升。**

需要这份系统化的资料的朋友，可以添加戳这里获取

一个人可以走的很快，但一群人才能走的更远！不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！