软件设计文档包含的内容

转行做IT开发已经三年了，应该了解并学会写出软件设计文档，这样才能够走的更远。

为什么要写设计文档？

设计文档也就是技术规范，用于描述你打算如何解决问题。

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

如果你的项目需要一个人月或更长时间，那么就应该编写设计文档。另外，一些小型项目也可以从迷你设计文档中获益。

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

标题和人物

设计文档的标题、作者（应该与计划参与项目的人员名单相同）、文档的评审人员，以及文档的最后更新日期。

摘要

摘要可以帮助公司的每位工程师理解文档的内容，并决定是否需要继续阅读文档的剩余部分。摘要最多可以包含3段内容。

背景

描述要解决什么问题、为什么需要这个项目、人们需要哪些知识才可以评估这个项目，以及它与技术战略、产品战略或团队的季度目标之间的关系。

目标和非目标

目标部分应该包括：

描述项目对用户的影响——你的用户可能是另一个工程团队或另一个系统。

指定如何使用指标来度量项目的成功——如果可以链接到指标仪表盘那就更好了。

非目标也同样重要，用于描述项目不会解决哪些问题，让每个人都达成共识。

里程碑

一系列可衡量的检查点，你的PM和上司可以借助它们大致了解项目的每个部分将在什么时间完成。如果项目时间超过1个月，我建议你将项目分解为面向用户的里程碑。

在设定里程碑时可以使用日历日期，把延期、假期、会议等因素都考虑进去。

当前的方案

除了描述当前的实现之外，还应该通过示例来说明用户如何与系统发生交互以及数据是如何流经系统的。

提议的方案

有人把这部分称为技术架构。这部分也可以通过用户故事来进行具体化，可以包含多个子部分和图表。

先从大处着手，然后填充细节。你要做到即使你在某个荒岛上度假，团队的其他工程师也能按照你的描述来实现解决方案。

其他替代方案

在提出上述解决方案的同时，你还考虑了其他的方案了吗？替代方案的优点和缺点是什么？你是否考虑使用第三方解决方案——或使用开源解决方案——来解决问题，而不是自己构建解决方案？

监控和警报

人们经常把这部分视为马后炮，甚至直接忽略掉。而在发生问题后，他们就手忙脚乱，却不知道该怎么办，也不知道为什么会发生这些问题。

跨团队影响

这样会增加轮班待命和DevOps的负担吗？

它的成本是多少？

它会增加系统延迟吗？

它会暴露系统安全漏洞吗？

它会带来哪些负面后果和副作用？

支持团队该如何与客户沟通？

讨论

这部分可以包含任何你不确定的问题、你想让阅读文档的人一起权衡的有争议的决定、对未来工作的建议，等等。

详细的范围和时间表

这一部分的主要阅读对象是参与该项目的工程师、技术主管和经理。因此，这部分放在文档的最后。

从本质上讲，这是项目计划的实施方式和时间细分，可以包含很多内容。