转载声明：文章来源https://zhuanlan.zhihu.com/p/422105989

既然编写设计文档可以更好的帮助我们在开发前阶段进行趋利和避害，那么编写设计文档应该是一件很有必要的事情了, 在这个判断下, 我们新的问题是: 如何写好一篇设计文档?

那么一篇合格的设计文档应该满足至少几个条件

内容完备：

设计文档体现的是用你的大脑去完整执行一遍需求流程的模拟, 它必须包含这个需求涉及到的全部环节、状态与环境, 你需要考虑到你的上下游和你的关系, 你如何请求服务或者别人如何使用你的服务, 你的页面是在什么环境下运行(浏览器/Webview/CEF), 以及这些相关环节如果出现问题对你的影响, 如果有一种情况被你疏忽了, 那可能都是线上问题或者是事故的祸根;

在设计你的页面和功能时, 你应该把这个页面或者组件的全部功能列举清楚, 这些页面或组件又有什么样的状态变化和交互, 只有把这些方面考虑齐全了, 才可能更客观的评估工作量的多少.此外, 在设计文档中应该收集齐开发需要的各类文档和资料, 以提升查找所需信息的效率, 例如笔者团队前端设计的文档模版中会收集如下内容

需求文档、设计视觉稿、服务端 IDL、第三方服务/SDK 文档、测试 Case、埋点文档、运营资源列表(optional)、走查及验收文档

结构清晰：

合理且清晰的文档组织能够反映你良好的思考顺序, 也便于他人理解, 笔者一般采用需求整体 - 页面 - 组件/模块这样的层次去组织设计方案, 就像你在开发一个 React/Vue 页面或组件, 也是先设计父组件, 再去思考组成它的子组件的功能(根据具体情况也可以先设计底层模块和服务), 就如庖丁解牛, 如果你能对整体结构和各个组成部分之间的结构和边界界定清晰的话, 相信你的代码模块化也会做的更好。

便于执行：

 一个理想的设计文档应该可以做到让别人来看你的文档也知道怎么实现需求(这个标准确实有些理想), 但是如果一篇设计文档写完你还是对如何进行开发毫无头绪或者存在疑点, 那么这片设计文档可能还不够完善, 更好的设计文档应该就像是乐高或者宜家的说明书一下, 看着文档你就应该对如何操作了然于胸。

以上是一些关于设计文档的理论描述, 下面让我们关注一些更具体的细节

如果你要开发一个新应用，创建新的 Git 仓库，项目初始化，项目部署流程，接入监控

如果你要开发一个新页面，页面的路由及相应的 query，页面的整体功能与结构设计

如果你要开发一个组件, 你需要思考:一个页面其实和组件的设计有很多共同之处, 他们都有三个组成部分；

State: 有哪些状态? 本地状态或需要通过接口获得的状态?；UI: 用户界面由哪些部分组成? 状态如何驱动 UI 的变化；Logic: 有哪些逻辑? 这些逻辑可以被归类为若干类子逻辑(操作数据、事件响应、调用服务), 这些逻辑会如何改变状态, 又如何响应用户的交互或者其他事件?