2024年最新如何编写好的软件设计文档_好的软件设计文档怎么写(2)，Golangstudio基础教程

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

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

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

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

标题和人员

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

概述

可以被公司里任何一个工程师所理解并且根据概要内容决定是否需要阅读文档的其余部分。这部分最多不超过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来制作图表。

提示：在截图下面增加一个可编辑版本的图表的链接，这样在发生变化时可以很容易的更新它。

包含数字

问题的规模往往会决定最终的方案。为了帮助评审人员了解整个问题的概况，列举出具体的数字，如数据库的行数，用户错误的数量以及这些数字如何随着使用情况扩展。还记得Big-O符号么？

试着有趣一些

设计文档不是学术论文。人们喜欢阅读有趣的东西，所以这是让读者更投入的一个好办法。但不要为了显得有趣而偏离了文档的主题。如果你和我一样，不是一个很有趣的人，Joel Spolsky给过这样的建议 — 最简单的显得有趣的方法是在进行一般性描述的地方，使用非常具体的例子。与其说『特殊利益群体』，不如说『左撇子的牛油果民』

做一轮自评

在把文档发给其他人评审之前，自己先评审一遍。你对这样的设计有什么问题和疑惑？如果有，就尽量先解决。

做一轮休假测试

加入你要休一个长假，并且没有网络，有没有团队的其他人根据这个文档可以按你的想法实现出来？正如前面说的，设计文档的主要目标不是分享知识，而是一种有效的方式来激发别人给你有用的反馈。

流程

又是讨厌的流程！设计文档可以帮你在浪费大量时间去实现一个错误的方案或者尝试去解决一个错误的问题之前获得反馈。获得好的反馈可以有很多方法，后面会写文章介绍。现在，让我们讨论下如何编写设计文档并获得反馈。

首先，参与项目的所有人都应该参与设计的过程。虽然技术主管会做出很多决定，但每个人都应该参加讨论并认同最终的决策。所以这篇文章里提到的"你"或者"你们"都是指参与项目的所有人。

其次，设计的过程不是说盯着白板天马行空的去畅想。往往需要你着手去做一些可能的原型方案。这不意味着你要在编写设计文档之前就去写生产级别的代码。不要那样做。但你必须要写一些代码去验证你的想法。为了确保你只是写一些实验性质的代码，制定一个如『原型代码永远不能被合并到主代码分支』这样的规则。

在您开始了解如何进行项目之后，你需要执行以下几个操作

1. 请你团队中经验丰富的工程师或者技术主管作为评审人。理想情况下这个人应该对要解决的问题域非常熟悉。可以买杯咖啡贿赂下:)
2. 在会议室放个白板
3. 把你要处理的问题跟这位工程师描述下。（这一步很重要，千万不要跳过）
4. 然后把你设想的实现方式解释给这位工程师，并说服他（们）。这是非常值得去做的一件事情。

这些工作甚至可以在你编写设计文档之前就做，在投入更多时间以及纠结于某个具体细节前，尽早的获得反馈。通常即便实现方法是一样的，你的评审人也可以指出你没想到的边界情况，澄清一些容易混淆的问题，以及指出你未来可能遇到的一些困难。

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

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

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

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

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

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