锐客网

  1. 首页 > 睿知 > >

如何才能写出好的软件设计文档？ 软件设计文档模板

生活知识睿知

软件设计文档模板(怎样才能写出好的软件设计文档？)
作为一名软件工程师，我花了很多时间阅读和编写设计文档 。经过上百份文档的磨练，我发现优秀的设计文档和项目的成功有着密切的关系 。
本文将介绍如何撰写一份优秀的设计文档 。
为什么要写设计文档？
文档也是技术规范，用来描述你打算如何解决问题 。已经有很多文章解释了为什么设计文档应该写在编码之前 。这里不再赘述，但我想再补充一点:
设计是确保工作正确完成的最有用的工具 。
该文档的主要目的是迫使您仔细思考设计并收集他人的反馈，以便更好地完成您的工作 。一般认为，设计文档的目的是让别人了解某个系统，或者作为参考文档 。这些只是设计文档有益的副作用，但绝不是其根本目的 。
根据经验，如果你的项目需要一个人月或更长时间，那么你应该写设计文档 。此外，一些小项目也可以受益于迷你设计文件 。
但是，不同的工程团队，甚至是同一个团队的工程师，写设计文档的方式是不一样的 。接下来，我们来谈谈优秀设计文档的内容、风格和流程 。
设计中应该包括哪些内容？
设计文档描述了问题的解决方案 。因为每个问题的性质不同，设计文档的结构也不同 。
这是一份清单 。你至少可以考虑在文档中包含这些内容 。
头衔和角色 。
文档的标题、作者(应该与计划参与项目的人员列表相同)、文档的审阅者(我们将在“过程”部分详细讨论)以及文档的最后更新日期 。
摘要
摘要可以帮助公司的每个工程师理解文档的内容，决定是否继续阅读文档的其余部分 。摘要最多可包含3个段落 。
背景
描述要解决什么问题，为什么需要这个项目，需要哪些知识的人来评估这个项目，以及它与团队的技术战略、产品战略或者季度目标的关系 。
目标和非目标
目标应包括:
描述项目对用户的影响——你的用户可能是另一个工程团队或者另一个系统 。
指定如何使用度量来衡量项目的成功——如果能链接到度量仪表板就更好了 。
非目标同样重要 。它们用来描述项目解决不了什么问题，让大家达成共识 。
里程碑
一系列可测量的检查点，通过这些检查点，你的项目经理和你的老板可以大致知道项目的每个部分何时完成 。如果项目时间超过1个月，我建议你把它分解成面向用户的里程碑 。
设置里程碑时，可以使用日历日期，考虑到延误、节假日、会议等因素 。例如:
开始日期:2018年6月7日
里程碑1-在黑暗模式下运行新系统MVP:2018年6月28日
里程碑2-抛弃旧系统:2018年7月4日
End:在新系统中增加新功能X，Y，Z:2018 . 7 . 14
如果其中一些里程碑的ETA发生了变化，就需要在这里添加【更新】，相关人员可以很容易的看到更新的内容 。
目前的方案
除了描述当前的实现，还应该举例说明用户如何与系统交互以及数据如何在系统中流动 。
这时候可以用用户故事 。记住，你的系统可能有不同类型的用户，他们的使用场景也不尽相同 。
拟议方案
有人称这部分为技术架构 。这一部分也可以通过用户故事来体现，用户故事可以包含多个子部分和图表 。
从大图开始，然后补充细节 。确保即使你在荒岛上度假，团队中的其他工程师也能按照你的描述来实现解决方案 。
其他选择
在提出上述解决方案的同时，有没有考虑过其他的解决方案？替代品的优缺点是什么？你是否考虑使用第三方解决方案——或者开源解决方案——来解决问题，而不是构建自己的解决方案？
以及监控和警报
人们往往把这一部分当作事后的想法，甚至直接忽略 。但是问题发生后，他们很着急，却不知道该怎么办，也不知道为什么会出现这些问题 。
跨团队影响
这样会不会增加倒班待机和DevOps的负担？
它的成本是多少？
会增加系统延迟吗？
会不会暴露系统安全漏洞？
会带来哪些负面后果和副作用？
支持团队应该如何与客户沟通？
讨论
此部分可以包含您不确定的任何问题、您希望阅读文档的人一起权衡的有争议的决定、对未来工作的建议等等 。
的详细范围和时间表
本部分的主要读者是参与项目的工程师、技术主管和管理人员 。因此，这一部分放在文件的末尾 。
本质上这就是项目计划的实施方法和时间分解，可以包含很多内容 。
我倾向于将这个部分视为项目任务跟踪器，因此每当范围估计发生变化时，我都会更新它 。但更像是个人喜好 。
怎样才能写好文档？
谈完了一份优秀的设计文档应该包含哪些内容，现在来谈谈写作风格 。
尽可能保持简单 。
不要把设计文档写成你读过的学术论文 。论文旨在打动期刊评论家，而设计文档旨在描述你的解决方案并获得他人的反馈 。您可以通过以下方式使文档更加清晰:
简单的词
使用短句
使用符号列表和编号列表 。
提供具体例子 。
添加图表
图表很容易比较几个选项，通常比文本更容易理解 。我经常使用Google Drawing来创建图表 。
请记得在截图下方添加图表源文件的链接，以便在图表发生变化时进行更新 。
包括数字 。
问题的大小通常决定了解决方案的大小 。为了更好地帮助审阅者了解情况，请在文档中使用实际数字，如数据库行数、用户错误数、延迟以及这些数据和使用情况之间的关系 。(还记得大O记号吗？)
添加利息
记住，技术规范不是学术论文 。另外，人喜欢看有趣的东西，但不要为了好玩而偏离核心思想 。
自我检查
在将设计文件发送给其他人审阅之前，假装成审阅者 。你对这份设计文件有什么疑问？然后解决这些问题再发文件 。
假期测试
如果你是独占性的，不能上网，团队里的其他人可以看这个文档，按照你的意图执行里面的内容吗？
文档设计的主要目的不是分享知识，但它是评估清晰度的好方法，这样别人可以给你提供有用的反馈 。
流动
设计文档可以帮助你在浪费大量时间实现错误的解决方案或解决错误的问题之前获得反馈 。获得好的反馈是一门艺术，但那是另一回事了 。现在，让我们讨论如何获得设计文档的反馈 。
首先，参与项目的每个人都应该参与设计过程 。即使很多决策是技术总监做的，也没关系 。至少每个人都应该参与讨论并收到他们的设计 。
其次，设计过程不一定是盯着白板，在上面画各种创意 。你们可以一起工作来构建各种可能的解决方案原型 。这不同于在编写设计文档之前编写代码 。请随意编写一些一次性代码来验证您的想法 。为了确保您的代码仅用于概念验证，原型代码都不能合并到主代码中 。
在您了解如何继续进行项目后，请执行以下步骤:
请团队中有经验的工程师或技术负责人审阅您的文档 。理想情况下，评审者应该是一个受人尊敬的人，他已经熟悉问题的边缘情况 。
在会议室用白板复习 。
向评审人员描述你正在解决的问题(这是非常重要的一步，不要跳过！) 。
然后向评审者解释你想如何实现你的想法，让他们相信这是正确的解决方案 。
在开始撰写设计文档之前完成所有这些步骤，可以让您在投入更多时间和最终确定解决方案之前尽快获得反馈 。通常情况下，即使实现模式可以保持不变，评审人员仍然会指出一些你需要覆盖的极端情况，或者潜在的歧义，并预测你未来可能遇到的困难 。
然后，在你写好设计文档的初稿后，请之前的评审人员再读一遍，并在设计文档的“标题和人”部分写上自己的名字，作为对评审人员的鼓励，也意味着对自己的评审行为负责 。
添加审核人姓名时，考虑针对具体问题添加不同的审核人(如SRE和安全工程师) 。
审核后，请将设计文档发送给您的团队，以获得更多反馈 。我建议把这个时间限制在一周左右，以免耽误 。尽量在一周内解决他们遗留的问题 。
最后，如果您与审阅者和其他阅读本文档的工程师之间存在争议，我强烈建议您将这些争议放在文档的“讨论”部分 。然后，与各方召开会议，讨论这些差异 。
如果一个话题有5条以上的评论，面对面的讨论往往效率更高 。记住，即使你不能让所有人都同意，你仍然可以做出决定 。
最近和Shrey Banga聊到这个的时候，了解到Quip也有类似的流程，只不过除了让团队中有经验的工程师或者技术负责人担任审核人之外，他们还建议让不同团队的工程师来审核设计文档 。我还没有尝试过这种方法，但是我确信这将有助于从不同观点的人那里获得反馈，从而进一步提高文档的质量 。
完成以上所有步骤后，接下来就是开始实施了！在实现设计的过程中，设计文档可以视为一个活动文档 。当您对实施计划进行调整时，也要更新文档，这样您就不需要一遍又一遍地向所有风险承担者解释这些变化 。
那么，我们如何评价一个设计文档的成功呢？
我的同事Kent Rakip对这个问题的回答是:如果你能获得正确的投资回报率(ROI)，那么这个设计文档就是成功的 。也就是说，一份成功的设计文件可能会导致:
你花了5天时间编写设计文档，迫使你充分考虑技术架构的不同部分 。
您从评审人员那里得到反馈，并且知道架构的某些部分具有更高的风险 。
为了降低项目的风险，您决定先解决这些问题 。
3天后，你发现这些问题要么是不可能的，要么比你原来想象的要难很多 。
你决定停止这个项目，去做其他工作 。
本文开头我们说过，设计文档的目的是为了保证工作的正确完成 。在上面的例子中，因为设计文档，你只用了8天时间就决定停止项目，而不是浪费几个月 。在我看来，这似乎也是一个非常成功的结果 。
【如何才能写出好的软件设计文档？ 软件设计文档模板】

    推荐阅读


    上一篇：流沙河的作品理想 理想流沙河

    下一篇：四大教哪四个 四大教主