设计文档应该怎么写?
作为一名软件工程师,如何写好一份优秀的设计文档,是十分重要的。
本文试图描述如何才能写好一份设计文档。
本文分为4个部分:
- 为什么要写一份设计文档
- 要包含在设计文档中的内容
- 怎么写
- 相关过程
为什么要写一个设计文档?
设计是软件过程的一个重要环节。而设计文档的编写,更是设计阶段的重要产物。设计文档也被业界人士认为是技术规范,描述是如何解决或实现需求中内容,最终于愿景达成最终一致性的比较文件。设计文档是确保正确完成工作的最有用工具。
设计文档中应该包含哪些内容?
设计文档描述了问题的解决方案。由于每个问题的性质不同,您自然希望以不同的方式构建您的设计文档。
首先,以下是您应该至少考虑在下一个设计文档中包含的部分列表:
标题和参与者
您的设计文档的标题,作者(应该与计划参与此项目的人员列表相同),检查者(我们将在“处理”部分中详细讨论),以及最后更新日期。
概览
高度概括的,公司的每位工程师都应该理解并能够通过阅读概览来决定是否有必要阅读其余的文档。最多3段。
背景
对手头问题的描述,为什么这个项目是必要的,人们需要知道什么来评估这个项目,以及它如何适应技术战略,产品战略或团队的季度目标。
目标和非目标
目标部分应包括:
描述项目的用户驱动影响 - 您的用户可能是另一个工程团队甚至是另一个技术系统
指定如何使用指标衡量成功 - 如果您可以链接到跟踪这些指标的仪表板,则可以获得奖励
非目标同样重要,它描述了您不会修复哪些问题,因此它也和目标在同一页面上。
里程碑
一个可衡量的检查点列表,因此您的PM和您的经理的经理可以浏览它并大致了解项目的不同部分何时完成。如果项目超过1个月,我建议您将项目分解为面向用户的主要里程碑。
使用日历日期,以便考虑无关的延迟,假期,会议等。它应该看起来像这样:
开始日期:2018年6月7日
里程碑1 - 以暗模式运行的新系统MVP:2018年6月28日
里程碑2 - 下掉旧系统:2018年7月4日
结束日期:将功能X,Y,Z添加到新系统:2018年7月14日
如果其中一些里程碑的ETA发生变化,请在此处添加[更新]子部分,以便相关方可以轻松查看最新的情况。
当前解决方案
除了描述当前的实现之外,您还应该通过一个高级示例流来说明用户如何与此系统交互和/或数据如何通过它。
用户故事是构建此框架的绝佳方式。请记住,您的系统可能包含具有不同用例的不同类型的用户。
推荐解决方案
有人称之为技术架构部分。再次,尝试通过用户故事来具体化这一点。可以包含许多子部分和图表。
先提供一张大图,然后填写大量细节,确保即使你出去度假了,团队中的另一位工程师也可以阅读它并按照你的描述实施解决方案。
替代方案
在提出上述解决方案时,您还考虑了什么?替代品的优点和缺点是什么?您是否考虑购买第三方解决方案 - 或使用开源解决方案 - 解决此问题而不是构建自己的问题?
监控和警报
我喜欢包括这一部分,因为人们经常事后才去考虑它们或者干脆忽略它们,当事情出了岔子,他们一筹莫展。
跨团队配合方面
是否会增加外呼和开发团队的负担?
它会花多少钱?
它是否会导致系统延迟?
它是否暴露了安全漏洞?
有什么负面后果和副作用?
支持团队如何与客户沟通?
讨论
任何你不确定的公开问题,你想让读者权衡的有争议的决定,建议未来的工作,等等。
详细的范围和时间表
本节主要是由参与该项目的工程师,他们的技术主管和他们的经理阅读。因此,本节在文档的最后。
从本质上讲,这是您计划执行项目每个部分的方式和时间的细分。有很多内容可以准确地确定范围,因此您可以阅读这篇文章以了解有关范围的更多信息。
我倾向于将设计文档的这一部分视为正在进行的项目任务跟踪器,因此每当我的范围估计发生变化时,我都会更新它。但这更多的是个人偏好。
怎么写
下面让我们来谈谈写作风格。我保证这与你的高中英语课不同。
写得尽可能简单
不要试着写你读过的学术论文。它们是为了给期刊评论家留下深刻印象。您的文档是为了描述您的解决方案并从您的队友那里获得反馈而编写的。多运用类似这些:
- 简单的话
- 短句
- 项目符号列表和/或编号列表
- 具体的例子,如“用户爱丽丝连接她的银行账户,然后…”
添加大量表格和图示
表格通常可用于比较几个可能的选项,图表通常比文本更容易解读。我已经用Google Drawing创建图表了。
专业提示:请记住在屏幕截图下添加指向图表的可编辑版本的链接,以便以后在事情不可避免地发生变化时轻松更新。
包括数字
问题严重程度通常决定了解决方案。为了帮助审阅者了解实际状况,请包括实际数字,如数据库行数,用户错误数,延迟 - 以及这些数据如何随着使用情况而扩展(请记住您的Big-O表示法?)。
试着变得有趣
规范不是学术论文。此外,人们喜欢阅读有趣的东西,所以这是让读者保持参与的好方法。尽管如此,不要喧宾夺主。
进行测试
在将设计文档发送给其他人进行审核之前,请自己作为审核人员过一遍。您对此设计有什么疑问?然后先发制人地解决它们。
做假期测试
如果您现在无法访问互联网,那么您团队中的某个人是否可以阅读该文档并按照您的意图实施该文档?
设计文档的主要目标不是知识共享,但这是一种评估清晰度的好方法,以便其他人可以实际为您提供有用的反馈。
处理
设计文档可帮助您在浪费大量时间实施错误解决方案或解决错误问题之前获得反馈。获得良好反馈有很多艺术,但这是以后的事。现在,让我们专门讨论如何编写设计文档并获取反馈。
首先,参与项目的每个人都应该参与设计过程。如果技术主管最终推动了很多决定,那也没关系,但是每个人都应该参与讨论并参与设计。因此,本文中的“你”是一个真正的复数“你”,包括项目中的所有人。
其次,设计过程并不意味着你盯着白板写些理论化的想法,随意制作潜在的解决方案原型。这与在编写设计文档之前开始为项目编写生产代码不同,不要那样做。但你绝对应该随意写一些一次性代码来验证想法。
之后,当您开始了解如何进行项目时,请执行以下操作:
- 请您团队中经验丰富的工程师或技术负责人成为您的评审员。理想情况下,这将是一个受到尊重和/或熟悉问题细节的人。
- 进入带白板的会议室。
- 向这位工程师描述你正在解决的问题(这是非常重要的一步,不要跳过它!)。
- 然后解释你想到的实现,并说服他们这是正确的构建。
在开始编写设计文档之前完成所有这些操作可以让您在投入更多时间并接受任何特定解决方案之前尽快获得反馈。通常情况下,即使实施保持不变,您的审核员也可以指出您需要覆盖的极端案例,指出任何潜在的混淆区域,并预测您以后可能遇到的困难。
然后,在您撰写了设计文档的粗略草稿之后,让相同的审阅者再次阅读它,并通过在设计文档的“标题和人物”部分中添加他们的名称作为审阅者来标记它。这为审阅者创造了额外的激励和责任。
在这方面,考虑为设计的特定方面添加专门的审阅者(例如SRE和安全工程师)。
一旦您和审核人员确定了,请随时将设计文档发送给您的团队,以获得额外的反馈和知识共享。我建议将反馈收集过程的时间限制在1周左右,以避免延误。致力于解决人们在该周内留下的所有问题和评论。
最后,如果您,您的审阅者和其他阅读该文档的工程师之间存在很多争议,我强烈建议您在文档的“讨论”部分中合并所有争议点。然后,与各方召开会议,当面谈论这些分歧。
每当讨论主题长度超过5条评论时,转向当面讨论往往效率更高。请记住,即使每个人都无法达成共识,您仍然有责任进行最后的沟通。
在最近与Shrey Banga谈论此事时,我了解到Quip有一个类似的过程,除了在您的团队中拥有经验丰富的工程师或技术负责人作为审阅者之外,他们还建议让不同团队的工程师审核该文档。我没有尝试过这个,但我当然可以看到这有助于从不同角度的人那里获得反馈,并提高文档的一般可读性。
完成上述所有操作后,即可开始实施!对于额外的布朗尼点,在实施设计时将此设计文档视为活文档。每次您更改原始解决方案或更新范围的内容时,请更新文档。这样你就不必向所有利益相关者反复解释事情,你会感谢我的。
最后,让我们真正了解一下:我们如何评估设计文档的成功?
我的同事Kent Rakip对此有一个很好的答案:如果完成正确的投资回报率,设计文档就会成功。这意味着成功的设计文档实际上可能导致这样的结果:
- 您花了5天时间编写设计文档,这迫使您通过技术架构的不同部分进行思考
- 您可以从审阅者那里获得反馈,即X是建议架构中最具风险的部分
- 您决定首先实施X以降低项目风险
- 3天后,你发现X要么不可能,要么比你原先想要的要困难得多
- 您决定停止处理此项目并优先处理其他工作
在本文开头,我们说设计文档的目标是确保正确的工作完成。 在上面的示例中,由于这个设计文档,您可能只花了8天时间而不是浪费几个月才能中止此项目。 对我来说似乎是一个非常成功的结果。
本文由网易云社区简译,更多详情请参见原文。
原文地址
设计文档应该怎么写?相关推荐
- 写好一份软件开发设计文档
如何写好一份软件开发设计文档 转载: 设计文档 - 也被称作技术规范和实现手册,描述了你如何去解决一个问题,是确保正确完成工作最有用的工具,其目的是迫使你对设计展开缜密的思考,并收集他人的反馈,进而完 ...
- 如何写出一份优秀的软件设计文档
作为一名软件工程师,我花了很多时间阅读和编写设计文档.在完成了数百篇这些文档之后,我亲眼目睹了优秀设计文档与项目最终成功之间的强烈关联. 本文试图描述什么使设计文档变得更好. 本文分为4个部分: · ...
- 如何才能写出好的软件设计文档?
作为一名软件工程师,我花了很多时间在阅读和撰写设计文档上.在磨砺了数百篇文档之后,我发现,优秀的设计文档与项目的成功之间有着密切的联系. 这篇文章将介绍怎样才能写出一份优秀的设计文档. 为什么要写设计 ...
- 怎么写出一份令人惊叹的设计文档?
点击上方"朱小厮的博客",选择"设为星标" 后台回复"书",获取 后台回复"k8s",可领取k8s资料 一份好的设计文档 ...
- 局域网聊天软件 设计文档怎么写?
局域网聊天软件 设计文档怎么写?这种针对数据库记录的 局域网聊天软件 窃取,被一些攻击者称为拖库,于是有了一个自然而谐音的戏称脱裤.只是攻击者日趋不厚道,从前只是偷了人家的裤子,现在还要晾在大街上,并 ...
- 【译】如何写出一份优秀的软件设计文档
作为一名软件工程师,我花了很多时间阅读和编写设计文档.在完成了数百篇这些文档之后,我亲眼目睹了优秀设计文档与项目最终成功之间的强烈关联. 本文试图描述什么使设计文档变得更好. 本文分为4个部分: 为什 ...
- 如何写出令人惊叹的设计文档?
与优秀的人在一起,自己也会优秀起来,点击加入 来源:DeepNoMind 一份好的设计文档需要提供清晰的问题描述.整体的概要设计.涵盖各个细节的详细设计等. 这篇有趣的英文小短文通过一个简单的小例子介 ...
- 如何写好方案规划设计文档,这里有一份实践清单
上一篇,<如何写好项目规划和方案设计文档>重点讲述的是撰写项目规划和方案设计文档的指导原则,要写成什么样子才能发挥它应有的价值. 具体如何做到,往往还需要实践经验和技术功底的支撑,仅仅知道 ...
- 如何从数据库中筛选出达成指定里程碑节点的项目_【译】如何写出一份优秀的软件设计文档...
作为一名软件工程师,我花了很多时间阅读和编写设计文档.在完成了数百篇这些文档之后,我亲眼目睹了优秀设计文档与项目最终成功之间的强烈关联. 本文试图描述什么使设计文档变得更好. 本文分为4个部分: 为什 ...
- Google工程师是怎么写设计文档的?
文章来源:[公众号:分布式实验室] 一份好的设计文档需要提供清晰的问题描述.整体的概要设计.涵盖各个细节的详细设计等. 这篇有趣的英文小短文通过一个简单的小例子介绍了Google工程师是怎么写设计文档 ...
最新文章
- 终身成长究竟有多重要?
- 主流Java学习路线
- 剑指 Offer 07. 重建二叉树【千字分析,三种方法】
- 超过50万的存款,该放同一个银行还是多个银行?
- LeetCode 481. 神奇字符串(找规律)
- start running 开始跑步减肥
- 成信大c语言答案P239.C,2011秋季江苏省计算机二级C语言试题与答案.doc
- Asterconference Asia 2012 中国大会
- DirectX 入门知识
- 最新版腾讯防水墙(二代)识别
- c语言定义浮点变量i和j,2012年计算机等级考试二级C语言基础教程:数据类型、变量和运算符...
- 当他不再爱你的时候!
- 11.28计算机导论课后总结
- 阿联酋金融机构举办加密资产及金融科技论坛
- SQLserver未发现数据源名称并且未指定默认驱动程序
- 藏经阁(学习资料汇总)
- 5.6.16mysql免安装_win7 64位配置mysql 5.6免安装版,初始化配置
- 2022全新恶搞放屁小程序源码(云开发)
- 富力集团解码“新高端医疗”
- C/C++校园疫情防控信息管理系统