提效 | 如何写好设计文档

设计文档可以说是日常工作中非常重要但又容易被忽略的部分. 好的设计文档是项目成功的重要基石.

本文将介绍如何才能写出一份优秀的设计文档.

一.为什么要写设计文档?

设计文档的主要目的是使你对设计进行强制性思考, 并收集他人的反馈, 以便更好地完成你的工作. 同时也是让其他人了解系统的参考文档.

可以说, 设计文档是确保正确完成工作最有用的工具.

接下来, 一起看下优秀的设计文档需要包括哪些内容, 又应该如何写出好的设计文档.

二. 设计文档应该包含哪些内容?

设计文档描述了问题的解决方案, 问题的不同, 设计文档的结构也不一样. 下面介绍的各部分, 可以根据需要写到文档中.

2.1

标题和参与人员

主要包括设计文档的标题; 作者或者参与研发的开发人员; 文档的评审人员;以及文档的更新履历;

2.2

摘要

摘要可以帮助每位参与人员理解文档的内容.

2.3

背景

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

2.4

目标和非目标

目标部分应包括: 描述项目对用户的影响; 衡量项目成功的指标;

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

2.5

里程碑

里程碑是一系列可衡量的检查点, 管理者可以借助它们大致了解项目的每个部分将在什么时间完成. 尤其是研发时间较长的项目,它给人的第一感觉就是项目可控. 在制定里程碑时可以使用日历日期, 把延期, 假期, 会议等因素都考虑进去.

例如:

• 开始日期: 2020年12月10日

• 2020年12月20日—完成研发测试工作

• 2020年12月25日—以金丝雀方式上线, 导流5%用户,进行数据分析及用户反馈收集.

• 2020年12月30日—数据分析用户反馈没有问题的前提下, 全面上线.

如果里程碑, 需要添加 [ 更新 ], 使相关人员可以很容易看到更新的内容.

2.6

当前的方案

除了描述当前的实现之外, 还应该说明用户如何与系统交互以及数据是如何流转的. 这个时候可以使用用户故事.

用户故事包含三个要素：

角色（who）：谁要使用这个

活动（what）：要完成什么活动

价值（value）：为什么要这么做，这么做能带来什么价值

2.7

提议的方案

一般为技术架构. 先从大处着手, 然后填充接口, 表结构等细节. 团队的其他人员也能按照你的描述来实现解决方案.

2.8

其他替代方案

在提出上述解决方案的同时, 你还考虑了第三方解决方案或使用开源解决方案等其他的方案了吗?替代方案的优点和缺点是什么?

2.9

监控和警报

主要监控数据以及性能告警等, 都要提前准备好.

2.10

其他影响

这样会增加轮班待命和 DevOps 的负担吗? 成本是多少? 会增加系统延迟吗?会暴露系统安全漏洞吗? 会带来哪些负面后果和副作用? 运营团队该如何与客户沟通?

2.11

讨论

记录不确定的问题, 有争议的决定, 对未来工作的建议, 等等.

2.12

详细的范围和时间表

可以包含项目计划的实施方式和时间细分等等很多内容.

三. 怎样才能写好文档

在讲完优秀的设计文档应该包含哪些内容之后, 现在让我们来谈谈写作风格.

3.1

尽可能简单

文档要简洁清晰, 不要当成论文在写, 主要注意以下四点

• 用词简单

• 使用短句

• 使用符号列表和编号列表

• 提供具体的示例

3.2

添加图表

合理利用图表会比文本更容易理解. 例如, 架构图, 流程图, 功能列表等等.

3.3

包含数字

在说明数据库行数, 用户错误数, 延迟等问题时, 使用明确的数字表示, 会使你的文档更准确更有说服力.

总结

最后, 设计文档使你强制性对设计进行整体思考, 降低风险, 同时也是传达思想, 快速沟通的一种方式, 不要舍本求末, 过于纠结文档内容和格式.