为什么要写设计方案或者项目文档

为什么要写设计方案或者项目文档

撸代码前，写下设计方案

为什么要写设计方案

解决一个复杂的问题，一般要经过几个不同的步骤。其中最重要的是问题发现阶段，分析阶段，和构建交付阶段。在分析阶段，工程师们研究哪些方案可以解决客户需求。一个设计方案，不代表已经有了可以上线的代码，虽然在验证方案的过程中，有可能会写一些代码。设计方案，是分析阶段的成果，它告诉大家: 你是怎么解决问题的？你的方案是什么？

写设计方案的好处

写下来一次，随时随地用

• 产品经理： 保证对问题一致的理解，并且知道方案的优势及其劣势，不会到后期发现劣势而导致意外
• 项目经理：阐明方案所做的假设以及可能出现的风险，帮助在项目执行过程中追踪这些风险
• 团队成员和其他团队负责人: 收集大家对方案的看法，接受大家对所选方案的挑战，保证你的方案凝聚了各种思维的光辉
• 老板：当成汇报，帮助老板看到你们的成果，并且给他提供一个管中窥豹的机会，让他看到你们整个团队的合作质量
• 质量工程师： 说明你们要构造的是什么，帮助他们写出好的测试
• 团队的新人：帮助新人获取知识，所有的设计方案积累起来，就是一部团队发展史，帮助新人了解大厦是如何一层一层建起来的
• 问题复盘时的回顾

设计方案需要有那一些内容

需求背景

为什么做这个需求

目标

需要达到什么目标

设计思路

解释如何一步一步的实现解决方案。一个准确完成的描述会告诉读者你问题的复杂度。

可信性分析

说明该软件开发项目的实现在技术上、产出比上的可行性，评述为了合理地达到开发目标可供选择的各种可能实施方案，说明并论证所选定实施方案的理由。

详细设计

对设计思路的详细解释。比如整体架构设计、DB设计、Cache 设计、接口设计、接口变动、依赖方文档

风险

描述方案可能存在的风险，如果有替代方案，在这里可以描述

如何测试

描述如何对方案的实现进行测试，测试同事会比较关注这一点

资源投入

描述实现技术方案的资源投入、包含人力资源投入、硬件资源投入

发布方案

这里描述的是如何部署你的项目，需要包含灰度方案、部署方案、回滚方案、

上线后数据

项目上线之后的收益？需要从线上拿到具体的数据。比如QPS、TPS、延迟以及对于用户产生的实际收益如何

留下你的项目文档

为什么要写项目文档

写文档，其实对个人、对项目、对团队，都是非常重要的事情。

• 帮助写文档的人理清楚思路
• 便于未来的维护和交接
• 节省自己的时间
• 便于团队更好的协作沟通

项目文档要有那一些内容

系统概述

简单描述系统是做什么的，如何工作的

名称解释

一些系统内用到的名称解释，需要在这里描述，要不然，看文档的人看半天也许不知道是什么意思

系统设计

系统的详细设计、包含架构设计、运维架构

架构设计

架构分析

对整体流程的描述

设计思想

设计思路

技术分析

使用的技术点分析

运维架构

运维架构

描述项目的部署架构图

如何部署

如何在本地搭建开发环境、如何部署测试、线上环境

如何测试

开发如何测试、测试如何测试

线上问题记录

排查线上问题的记录

功能模块设计

描述系统各个模块的设计、比如API设计、API流程图

API设计

模型设计

描述数据库设计和缓存设计

数据库设计

数据库表字段的描述、对索引设计的解释

Cache设计

缓存的设计，写TPS、读QPS

FAQ

常见问题解答

参考

• 软件标准项目文档