如何写出一个好的设计文档

原创 2018年04月16日 20:25:37

1.概要

大部分的工程师都不重视设计文档的书写,对于一个需求,都是经过一些简单的讨论,写一个简单的方案甚至就是自己简单的想想就开始进行编码的工作。

往往这种开发方式会导致开发人员对细节考虑不周,开发过程中会带来许多的坑,在今后采坑或者补坑的路上耗费大量的人力,轻则影响上线时间,重则上线了出现case,影响业务。

写设计文档和是能够帮助开发人员完成 是什么->做什么->怎么做 的思路梳理过程。比如,你可能对一个技术或者概念很熟悉了,但是你在要说出来或者写出来给别人看的时候,或许就会发现有些技术的细节你没有考虑清楚。

当你在写一个设计文档的时候,会逼迫你自己去把每一个细节都弄清楚,想明白。这样,在实际的开发过程中才会少踩坑,不踩坑。

2.好的设计文档需要哪些内容

对于一个设计文档的书写,应该满足STAR原则,同时一个好的设计文档需要考虑业内的各种实现方案,不能闭门造车。

基于此我认为主要会分为8个部分。分别为 项目背景,项目目标,需求分析,方案对比,概要设计,详细设计(存储模型设计,接口设计),开发以及上线计划,方案排期。

对于详细设计中,需要存储应该有存储模型的设计,需要交互应该有相应接口的设计。下面详细说下每个部分的书写要点。

2.1项目背景

主要是梳理下目前系统中的主要问题和痛点,主要问题和痛点的范围覆盖面很广,可以主要从 稳定性、业务、 运营的角度去分析。

  • 对于稳定性,具体的问题可以给出相应的数据指标,比如相关调用时间多少,TP90时间,客诉率,下单成功率等等。
  • 对于业务,具体可以从业务发展,业内痛点来进行分析
  • 运营,具体的问题也可以给出相应的数据指标,比如运维成本高大于XXpd等。

2.2目标

即自己做的这个方案上线后需要达到什么成果,具体目标需要结合项目背景来定。

  • 比如对于稳定性而言,需要降低一半的客诉率,将下单成功率提高到4个9等等。
  • 对于运维角度而言,需要将运维成本降低为0等等。

同样,具体的问题需要具体分析,定目标时可以参考目前业内或者公司内部的相关系统的指标

2.3需求分析

理论上来说,需求分析是PM来做的事情,但是通过需求分析,开发人员能够更加清晰的了解和明确相应用户的需求,也可以通过需求分析了解PM有时的需求是否是“伪需求”。

相关功能的优化以及系统的演进目的都是为了给用户提供更好的服务,在进行需求分析时,开发人员应该尽量的使用下自己的系统,以便能够真正的了解自己的系统。需求分析的要求是需要画出一个 用例图,用来描述用户的所有用例。

2.4方案对比

在进行方案设计时,其实也是一个方案调研的阶段,需要调研业内或者一些开源系统的相关功能实现。并与自身业务相结合,评估出一套最适合自己的业务。

方案对比主要是为了选择出一个适合于自己业务的,有时候不要为了技术而技术,简单合适反而是最佳的选择。

方案对比中可罗列出每个方案的开发流程以及需要注意事项,最后给出方案对比表格以及结论即可

2.5概要设计

在选择好了方案后,需要给出方案的概要设计,在概要设计中,用以描述整个方案的全景设计,一般来说需要包含方案全景设计图、流程图以及时序图

  • 全景设计图:如果设计方案是对于系统维度,那么设计图中需要体现出当前系统在整个链路中的调用关系,以及当前服务中相关的领域设计,相应领域中应该列出具体的相关功能;如果设计方案是系统内部的优化或者改造方案,那么需要画出内部的调用层级关系图,在图中应该需要标识出系统间的模块关系以及当前方案上线后的调用关系。
  • 流程图:流程图用于描述中方案的详细执行过程,如果方案是系统维度的则没有不用画出。
  • 时序图:时序图的维度可以是针对于服务与服务之间,显示出服务之间的调用,具体的接口可以列出相关服务的内部功能。

2.6详细设计

详细设计中包含方案的对比,存储,接口等详细设计。

存储模型设计

存储模型设计中需要给出相关存储模型图和相关表的DDL设计:

相关存储模型图为相关表的一对一,一对多映射关系,以及当前设计表的相关重要字段
DDL中需要给出相关的建表SQL,建表SQL中每个字段都需要强制给出默认值以及字段详细含义,最后需要给出相应的表索引

接口设计

接口设计中需要给出相应接口的定义,请求和响应对象的定义,如果是rpc接口,比如thrift还需要定义出相关的idl。另外还需要定义接口的超时时间等

  • 接口定义时,可采用swagger来自动生成文档
  • 接口只能新增和适配,没有100%的把握,不能轻易的删除来接口

2.7开发及上线计划

分为开发计划和上线过程

  • 开发计划:主要是列下主体的开发流程,具体可以列出一些方案里程碑的完成时间
  • 上线计划主要包括:
    • 如何进行灰度
    • 如何发布,发布后的check人
    • 如何进行验证
    • 回滚策略

2.8项目排期

给出项目的排期表格,表格中除各计划的相关内容外,还应该包括 预计估时,目前进度,是否delay,delay原因等等。

3.总结

设计文档不仅仅是写出来给别人看的,而且是一次深入思考的过程,写作的过程就是逼迫自己思考的过程,一篇好的设计文档不仅能使得阅读人员对于所要开发的功能一目了然,还避免了今后的采坑过程。

当然,这篇文章也并没有涵盖所有设计文档的写作,比如也可以通过MindManager画思维导图,或者使用其他的工作,只需要表现的清晰即可。

有设计文档写作建议或者有工具推荐的小伙伴欢迎留言讨论~

【UI】第四周 设计基础

本周主要讲解平面设计基础。在UI设计中,平面设计是设计师需要具备的基础技能。在本周的课程中,会讲到平面构成基础(点、线、面),版式设计原理,色彩构成以及图形创意。
  • 2018年04月23日 14:03

测试用例设计

  • 2012年12月13日 14:01
  • 877KB
  • 下载

如何写出一个好的程序

我们以memmove函数作为例子,来看我们如何一步步精简和优化你的代码。 写之前我们应该知道memmove这个函数有什么用? 他就是一个按字节的拷贝函数,把目标的内容按字节拷贝到你指定的地址,他和st...
  • Dawn_sf
  • Dawn_sf
  • 2017-01-23 15:05:52
  • 529

根据dtd例子写出xml文档

ceshi.xml文件 validate.html验证文件 相关概念说明: 一、XML概述 1、XML是可扩展标记语言。是由W3C指定并...
  • zhengleiqing
  • zhengleiqing
  • 2016-03-27 18:37:17
  • 2505

程序开发规范 程序开发规范

  • 2007年07月26日 11:55
  • 287KB
  • 下载

如何写一个递归程序

总是听到大大们说递归递归的,自己写程序的时候却用不到递归。其中的原因,一个是害怕写递归,另一个就是不知道什么时候用递归。这篇文章就浅析一下,希望看完之后不再害怕递归,这就是本文最大的目的。 递归到底有...
  • nxpzmj
  • nxpzmj
  • 2013-07-31 11:26:52
  • 2773

程序员如何写出一份好的文档?

在实际的软件开发工作中,除了编写代码之外,程序员还会花大量的时间来编写相关的研发文档,这些文档包括:详细设计文档、单元/集成测试文档、软件版本开发报告、软件安装说明、软件升级指导书等。 在《程序员既...
  • zhouzxi
  • zhouzxi
  • 2015-06-10 16:37:19
  • 6949

如何设计一个好的api

原文:How to design a good API翻译时间:31-08-2007译者:周林( 欢迎转载,转载请注明出处^_^) 摘要:    本文以NetBeans架构下API的设计为背景,描述了...
  • hiteny
  • hiteny
  • 2010-04-08 10:11:00
  • 1931

全程软件测试之测试需求分析与计划(1)

在项目启动之后,就要着手软件项目的计划,包括软件测试计划。软件测试计划是整个开发计划的组成部分,同时,它又依赖于软件组织过程、项目的总体计划、质量文化和方针。在测试计划活动中,首先要确认测试目标、范围...
  • broadview2006
  • broadview2006
  • 2014-02-24 15:24:19
  • 11045

设计一个算法的方法论

抽取算法设计共性为6个步骤,结合近段时间设计的一个算法撰写了这个方法论。主要用于总结经验,提高自身的生产力;如果不小心启发了他人,也算是对业界的一点小贡献。...
  • jiangjunjie_2005
  • jiangjunjie_2005
  • 2016-05-15 09:35:18
  • 1361
收藏助手
不良信息举报
您举报文章:如何写出一个好的设计文档
举报原因:
原因补充:

(最多只允许输入30个字)