做软件项目设计文档怎么写啊

事实上，撰写项目规划和设计文档，最重要的不是文档的模版和格式，而是里面的具体内容，它往往需要结合实际客观环境因素来综合考虑，平衡取舍，是一个需要充分脑力活动的工作。尽管如此，在大多数情况下，还是有一些相对通用的指导原则可以帮助我们更好的完成这项工作。

首先，需要有明确项目背景，目标，以及核心需求分析

换句话说，就是这个项目从产品或业务的角度，最核心的推动力是什么？再换句话说，痛点是什么？

有痛点自然就有目标，你希望项目最终以什么方式解决问题，能达成什么目标。

背景和目标的阐述，必须要能够自然合理的推导出下一部分内容：项目的核心需求/功能是什么。

如果项目背景，目标的描述不能起到这个作用，那这一节内容就没写好，因为项目方案文档就缺乏了根本的出发点，后续的内容都没有了好坏对错判断的基本依据。

举个例子，如果我想构建一个数据交换服务或ETL系统，那么上述各环节的内容可能是（简化的写）：

背景 ： 当前数据ETL链路极端难用，效率低下，稳定性差，维护代价高，用户抱怨多等等。

目标 ： 用户全自助，简单易用；可维护性好；性能高；可靠性好。

核心需求 ： 比如针对“用户全自助，简单易用”这点（其它目标可以类似分析推理），可能是：

提供统一的，标准化的配置后台：用配置的形式表达ETL业务语意，屏蔽下层实现细节。

提供完善的错误反馈信息/机制：让用户能自助解决使用中遇到的问题。

ETL业务流程标准化：将最佳实践沉淀下来，通过配置的方式让用户选择，减少重复工作，降低用户开发的难度，规避使用姿势错误可能造成的问题。

其次，需要对现状和问题进行充分的收集和分析

从方案文档的角度来说，放在这里，是为了进一步细化问题，分析目标，核心需求与当前现状的差距在哪里，具体有哪些实际问题需要解决。为后续具体的实现方案，准备必要的输入信息，确定工作的优先级，重要性，项目迭代的步骤等等。

需要强调的是，现状和问题分析，要围绕前面的核心需求的条目展开，两者是强关联的，不要相互脱节，各讲各的

最后，是输出解决方案

定完需求目标，分析完问题和现状，接下来才是规划具体做什么，怎么做，什么时候做

做什么：

做什么和前面项目目标的要求刚好截然相反，需要输出明确的可执行的事项，而不是模糊的不可执行的要求。

具体做的每一件事情，都要和前面的核心需求和现状问题对应上。如果你发现有些工作，和前面的目标没有任何关联性，那么考虑一下目标是否需要再评估调整，或者这件事情根本就是不重要的。

要做的事项列表，是一个经过归纳思考以后的总结，而不只是一个个零散的事情的随机列表。需要有重点和优先级。如果有必要，以归类，分组等形式结构化的组织相关联的事项。

完整的事项列表，应该是一个和最终目标对应的完整解决方案，而不仅仅只是完成目标工作中的某一个环节。

比如面向用户的终端产品项目，需要包括整个产品的交互逻辑，业务流程的规范设计等等，而不仅仅是对底层系统实现和后台功能点的设计。

这点很多同学也很容易忽略，总觉得功能和架构的实现才是有挑战，需要规划的内容，而产品的形态并没有花心思去琢磨，事后开发前端时才来考虑。实际上后者可能才是真正影响项目成功的关键，也很可能会影响到底层架构的设计和取舍。类比一下，好比一个用户产品都开发完了，才来考虑埋点，数据采集和数据分析的工作，这时候就很被动了。

怎么做：

前期方案文档，没有必要列出详细的技术方案细节，只需要一个整体的技术方向选型和初步的架构设想。但是，如果是涉及到核心需求能否有效满足的关键的技术点，有可能影响整体的架构或产品实现的，那就有必要就可能的方案的进行详细的评估并得出初步的结论。

无关架构或进度安排的方案细节，没有必要写太多，可以后续再补充。

方案中有不明确的地方，即使没有时间调研，也不要简单的略过不写，要在文档中明确的把问题写出来，给出下一步调研的方向计划等。归根到底，方案文档中，对每一个已知重要的问题，都需要一个明确的结论或者可以后续跟进的计划，以免事后遗漏。

再强调一下，做什么和怎么做就是手段，既然是手段，就要写得足够具体，具体到有明确的可落地实施的事情，有明确可以衡量的标准，或者针对当前存在的一个具体问题，不要在这个地方又写得像目标，没有明确的可执行的点。

继续举上文数据交换服务的例子，针对其中的一个核心需求：

ETL业务流程标准化：将最佳实践沉淀下来，通过配置的方式让用户选择，减少重复工作，降低用户开发的难度，规避使用姿势错误可能造成的问题。

这个内容要写具体的要做的事项。以下方式来写可能就是不合格的，因为不够具体，还没有足够思考：

总结最佳实践

生成标准的流程

总结常见的错误

以下内容可能就更加明确，更加可落地一些：

统一当前增量数据导入的存储，合并，归档方案

将常见合并，去重逻辑标准化，通过配置自动生成任务脚本

制定ODS快照表生命周期管理方案，规范存储路径和命名方式，定期清理过期数据。

什么时候做，谁来做：

这是做什么和怎么做的进一步延伸，需要强调的是整个项目如何实施的整体步骤计划，而不仅仅是简单的列一下每项工作的人员和排期，

需要分析系统可能的迭代步骤（包括可能的短期应急和长期解决方案），上下游依赖梳理，需要协同进行的工作，最终项目上线时可能的业务迁移，数据迁移，系统集成等等外围工作的安排。

如果不是工期严格要求，deadline为导向的项目，整体的依赖和步骤往往才是在项目规划阶段需要重点阐述的内容，也是有可能对整体产品的进度，风险产生影响的事项

而具体工作工期的安排，说实话，多数情况下，反到没有那么重要。如果整体工作和步调没考虑周全，工期排得再科学，再精细，也毫无意义。

总结一下，什么时候做什么事，最重要的目的，不在于工期的计算，甚至也不是人力资源的安排，而是为了理顺事情依赖关系，控制可能的意外风险，提升项目开发进度的可控性。

总体原则：

项目方案规划文档的根本目标是统一认识： 明确问题，确定重点，阐明路径，控制风险。

文档的撰写方式，是目标和需求先行，围绕出发点，逐步递进展开。

文档的基本要素： 背景，目标，核心需求，现状问题分析，关键方案难点解析，总体实施路径，工作事项列表，进度计划安排。

再细化到一些注意事项：

核心需求，必须是核心的,一定要实现的内容！不能缺，也不能滥。

问题现状，工作事项，必须呼应核心需求，要有明确的相关性，不要无的放矢。

围绕最终目标，输出完整的端到端的解决方案，而不是局部环节的方案。需要从最终产品/功能形态的角度考虑要做的事，而不是仅仅考虑底层技术实现。

事项目标列表，不要仅仅罗列要做什么事，更重要的是说明想要得到的结果，而不仅仅是描述实现手段。

所有工作事项，需要明确思考过实施步骤，重要性和优先级，结合目标和需求，进行抽象归纳，而非简单随机罗列。

要有明确的计划排期，但更重要的是，要完整的分析思考可能的上下游和周边工作依赖。排期只是结果，完整的梳理才是关键。

软件开发中文档的编写是一个不可缺少的环节，常见的如《需求分析》、《概要分析》、《数据库设计》等。在“软件人”的阵营里向来存在两种观点，注重文档还是关心代码。

我这里写一个《用户信息模块的概要设计文档》，只列举主要内容了

1.功能描述：用于完成系统用户信息的新增、删除、修改、查询；

2.功能用例：一个主用例用户信息，附加新增、删除、修改、查询4个子用例，操作人员为管理员，图形就不画了，很简单的；

3.业务流程：查询有效范围用户信息——》新增用户信息——》判断当前帐号是否存在——》存在给出提示，反之保存成功提示。

4.约束限制：超级管理员可操作所有（包含删除，我这里考虑仅是逻辑删除、非物理删除）的用户信息；系统管理员可操作除系统管理员、超级管理员外的全部用户信息；单位管理员可操作本单位用户信息；用户帐号信息系统内全局唯一；

5.系统性能：要求同时支持500个并发操作；页面操作响应时间小于1s；页面大小小于1kb；

当前用户所属员工信息不存在时，可直接进行员工信息的添加，并完成用户信息的同步保存，确保事务的完整性；

6.运行环境：依赖系统整体运行环境为准（存在特殊需要注明）；

7.操作实体：用户信息、员工信息、系统日志等。

8.异常处理：如果系统框架中已经提供相关说明，这里仅需要注明符合系统架构异常处理方式即可。

9.外部接口：输入—用户ID，输出—用户信息；

10.其他说明：用户帐号必须定义为字母开头，数字与字母组合，并保证全局唯一；用户密码采用md5算法加密，系统架构已提供相关接口。

11.注意事项：用户帐号不能为空，不能存在空格，不能超过6位；超级用户信息仅在系统初始化中完成其信息写入操作，其他用户无权对其进行修改。

项目组中也不是所有人都必须参与文档的编写，通常业务需求人员、设计人员、架构师、项目经理、小组长占大多数，而且这些人中很多也不是专注于写代码的角色。

·

详细设计是相对概要设计而言的，是瀑布开发流程的一个重要环节，在概要设计的高层设计的基础上，从逻辑上实现了每一模块的功能，是编码阶段的主要参考资料，是从高层到低层、逐步精化思想的具体实现。

详细设计文档的内容包括各个模块的算法设计，

接口设计，

数据结构设计，交互设计等。必须写清楚各个模块/接口/公共对象的定义，列明各个模块程序的

各种执行条件与期望的运行效果，还要正确处理各种可能的异常。

·

在开发过程中，由需求及设计不正确、不完整所导致的问题是项目进度拖延、失败的一个主要因素，而软件系统的一个重要特性就是需求和设计的不断构建和改进，在写详细设计文档过程中，

详细设计实际上是对系统的一次逻辑构建，可以有效验证需求的完整性及正确性。

如果不写详细设计文档，一般就从概设直接进入编码阶段，这时开发人员所能参考的资料就是需求规格说明书及页面原型、数据库设计等，不能直接进行开发，需要进行信息的沟通，把页面原型不能体现的设计讲清楚，这样既容易遗忘，也容易发生问题，详细设计文档可以作为需求人员、总体设计人员与开发人员的沟通工具，把静态页面无法体现的设计体现出来，包含整体设计对模块设计的规范，体现对设计上的一些决策，例如选用的算法，对一些关键问题的设计考虑等等，使开发人员能快速进入开发，提高沟通效率，减少沟通问题。

对于系统功能的调整，后期的维护，详设文档提供了模块设计上的考虑、决策，包括模块与整体设计的关系、模块所引用的数据库设计、重要操作的处理流程、重要的业务规则实现设计等等信息，提供了对模块设计的概述性信息，阐明了模块设计上的决策，配合代码注释，可以相对轻松读懂原有设计。

·存在的问题要由专门的人写，是比较麻烦的，也是很需要时间的，会对进度造成压力，也容易形成工作瓶颈，使设计人员负担过重，而开发人员无事可作。对于现在一般的以数据库为中心的管理系统而言，这个工作始终是要作的，区别只不过是不是形成专门文档，形成文档可能会多花一两周时间，但相对于规避的风险和问题来说，也是值得的，另外由于现在高级语言的流行，所以更详细的设计应该直接体现在代码的设计上，而文档则只体现设计上的一些决策，协调整体设计与模块设计的关系，把页面原型所不能体现的设计情况文档化，所以所花费的时间是有限的。

设计内容容易过细，但设计阶段是不能考虑特别清楚地，时间也不允许。

对于这个问题，一个对策是上边所提到的，文档只体现设计上的决策，页面原型所不能反映的信息，详细设计只体现总体设计对模块设计的一些考虑，例如对功能的数据库设计等等，而具体的实现实现，则到代码中再去实现，相关的设计也仅体现在代码中。

需求、设计需要不断的被更新、构建，则设计文档需要不断的重新调整，文档的维护需要跟上，否则文档和系统的同步就很难得到保障了，且造成多余的工作量。文档的内容易流于形势，质量糟糕，不能成为开发人员的参考手册，一是要建立起相关制度，如有修改，先改文档，后作开发，从工作流程上切实保障文档与系统的同步，二是要规范文档质量，对文档该写什么，不该写什么，标准是什么，粒度是什么，语法应该如何组织，有明确的标准和考虑，同时，建立审计文档评审、审核制度，充分保障系统的使用。·

首先是文档的内容，根据项目和团队的不同，详细设计文档的内容也有所不同，一般说来，粒度不宜过细，不能代替开发人员的设计和思考，但要把有关设计的决策考虑进去，包括与其他模块、整体设计的关系、操作的处理流程，对业务规则的设计考虑等，有一个标准为，凡是页面原型、需求规格说明书所不能反映的设计决策，而开发人员又需要了解的，都要写入文档。

其次是文档所面向的读者，主要为模块开发人员、后期维护人员，模块开发人员通过详细设计文档和页面原型来了解所开发的功能，后期维护人员通过实际系统、模块代码、详细设计文档来了解一个功能。

再有就是谁来写文档，因为文档主要考虑的是设计上的决策，所以写文档的人应该为负责、参加设计的技术经理、资深程序员，根据团队情况和项目规模、复杂度的不同，也有所不同。

还需要保证文档的可读性、准确性、一致性，要建立严格的文档模板及标准，保证文档的可读性及准确性，同时建立审核及设计评审制度，来保障设计及文档的质量，另外在工作流程中要强调，要先设计、先写文档，再进行开发。

一份设计文档的结构大概包括一下几部分的内容：项目背景、项目排期、版本历史、信息架构分析（包括站点地图、体验地图、流程图等）、产品框架设计、线框图和视觉稿等。

具体在设计文档中要展示哪些内容，取决于实际项目的情况，公司的具体规定、产品经理的个人工作习惯等，可能删减一些内容，也可能增加一些内容。

每个部分拆分开来，我们一起来看看具体是如何的。

》》

这一部分的内容在充分沟通需求之后完成。产品经理充分了解要设计的产品是什么，是什么平台上发布的，产品的用户群体是哪些类型，使用场景有什么，他们想通过这个产品解决什么问题，业务/产品现状，关键痛点是什么。把需要和需求方了解清楚之后，能够明确产品设计目标，要解决的需求是什么，根据这些需求，需要设计什么样的功能或者如何优化现有的功能，最终达到怎样的业务目标。

》》

和需求方确认各阶段交付物的时间节点，知道什么阶段要完成什么工作，达成什么目标。根据时间节点制定完成设计的具体计划，根据这个计划有节奏、有方向地展开工作，以较高的质量按时交付。

》》

每发生一次比较大的迭代更新，都要记录在版本历史记录里。这样做的好处是，可以清晰地展现设计稿的迭代历程，做了哪些需求的改动，设计思路发生什么样的变化，哪个部分是什么时候什么人负责的。对于产品设计的回溯，提供了极大的便利。相比一个个去翻以前的设计稿，查看版本历史记录更清晰，项目结束后浏览这一部分，也可以看到自己的设计在哪些方面哪个阶段存在不足，是如何被发现、改进和提升的，下一次设计的时候是否可以更早地思考到和回避掉。

》》

根据具体项目性质的不同，这一块的分析工具也有较大的差异，具体的选择和使用要按照实际场景来，而非机械进行套用。

如果是设计一整套网站系统，站点地图必不可少。站点地图可以对整个网站的架构可以构建起一个初步的印象，像架构层级过深、页面内容重复等问题都可以通过站点地图发现，以全局的角度去观察整个产品，而不是单一的某个功能、某个页面。

体验地图可以把产品在不同使用场景、流程下的体验问题直观地呈现出来，我们通过调研，会得到一些用户的体验反馈，但是通常比较杂乱、没有逻辑性。通过体验地图可以整理出用户使用产品大概有哪些场景和环节，各场景和环节下都遇到过什么样的问题，哪些问题出现的频率较高等，让产品经理能够更贴近用户，沉浸到使用产品的实际体验过程中去，进而思考各场景、环节下都可以进行怎样的设计目标拆解与设计优化、最终帮助完成产品的整体目标。

流程图也是一个常用工具，明确展示出用户使用产品的流程和步骤是怎样的。通过它可以查找步骤是否可以合并优化，能否抽象出通用的流程来构建框架设计等。

》》

产品框架设计构建起产品的轮廓，抽象出通用的布局原则，页面上大概有哪些模块，这些模块之间的主次、优先级关系是怎样的。整体规划把握界面的结构、模块之间的关系呈现等，而不是纠结于一些细枝末节和不重要的内容上。

》》

线框图在产品框架设计的基础上具化出了产品的完整骨架。在绘制线框图的时候需要仔细考虑到每一个可能的使用场景，包括负面、误用等特殊情况都要包括在内。

Axure是绘制产品经理绘制线框图的常用的工具。在Axure中，通过命名页面和调整层级关系，建立站点地图。在每个页面中根据场景画出线框图，包括具体的功能及场景，可以加以文字说明，辅助以用例交互。

线框图不是视觉设计稿，但在视觉效果呈现上却马虎不得。如果在绘制线框图的时候不考虑如产品尺寸、页面规范等，最终完成得会比较粗糙，也容易对内容的编排产生影响，导致整个页面结构都要被迫调整之类的情况，只能增加产品设计成本，而在最开始就注意这方面的问题，就可以尽可能地避免类似的情况发生。

》》

视觉稿作为产品设计的最终产出，在线框图的基础上完成配色、图标绘制等视觉细节，为产品“涂脂抹粉”。视觉稿选择关键场景的界面进行绘制表现，注意一些Hover/Active之类的状态表现，然后就可以标注交付前端了。

这是产品设计文档中比较常见也比较重要的的几部分内容，根据你自己的需要和公司的规定、项目的具体情况，选择需要重点体现的内容，也可以有所增删，并不是一成不变的。