工程文档编写

Posted 2020-12-16 tanbo

工程项目文档编写

引言

现在很多企业业务开展都离不开项目管理，项目文档管理，是指在一个项目运行过程中将提交的各类文档进行收集管理控制的过程。工程项目保存的文档要涵盖项目可研、总体设计、基础设计、详细设计等整个项目周期，其中包括项目系统管理、文档版本控制、文档质量管理等管理内容。项目经理可以从项目文档角度去把握项目进展情况。因此，工程项目文档对于一个项目的顺利进行有着至关重要的作用，其关键性不容忽视。

项目文档学习路线图

 

 一.项目流程概述

每个项目大致要经过调研项目、项目立项启动、项目计划、需求分析、需求变更、系统设计、构建开发、测试验收、部署试运行上线和项目总结的不同阶段。如图1-1-1所示展示了整个项目开发的流程。

 

图1-1-1 项目流程

1.项目角色

项目成员角色可以分为项目经理、产品经理、开发经理、测试经理。

l 项目经理为整个项目的核心，推动项目的整个进行，保证项目的交付。

l 产品经理主要负责设计项目需求，需求必须符合客户的需要。

l 开发经理主要进行软件设计以及代码实现，顺利的实现项目的要求。

l 测试经理主要负责对项目的质量进行审查，确保项目质量达到预期目标。

2.项目流程

1.项目立项

主要由项目经理组织项目人员进行项目启动会议，明确项目背景、需要实现哪些功能、项目交付时间等，其主要目的是要项目组成员明确项目的情况。

2.项目计划

由项目经理牵头各角色成员配合，制定项目的开发计划、项目的里程碑、风险计划、上线计划、验收计划等。其主要目的是为了让项目能够准时交付，各过程可控。

3.需求阶段

由产品经理根据项目的情况进行需求分析，整理出详细的需求内容，包括需求规格说明书、产品设计图、产品原型图、产品高清设计图等。项目需求在整个项目开发过程中十分重要。

4.设计阶段

在需求阶段之后即详细的需求已经确认，由开发经理组织相关的开发团队进行研发设计，该阶段分为概要设计和详细设计阶段。先对项目的实现进行概要设计，即设计系统的总体框架以及使用到的技术评估。概要设计完成后，由开发经理组织相关的项目成员进行技术评审会议，技术评审通过后方可进行详细设计，即详细的代码逻辑设计。 

5.开发阶段

在项目需求以及项目设计完成的情况下，由开发经理分配各开发成员的任务，由每个开发人员进行代码开发实现。在开发实现过程中，各开发成员要进行代码版本控制。确保代码和系统版本可控。

6.测试阶段

当项目功能实现后，且开发团队已经自己测试无大问题后，就可以提交测试团队进行最终的项目质量验证。验证的过程是一个迭代的过程，测试人员针对开发团队发布的内部测试版本，针对项目需求逐一认证，发现有问题的，则通过项目管理系统进行发布，开发人员进行问题解决，测试人员进行回归测试验证。 

7.试运行上线

当项目功能实现，且测试团队无发现重大问题，达到可以上线的标准后。则由开发经理负责部署正式的上线系统，并且试运行一段时间。如果在试运行期间发现严重问题，则还需要进行问题修改，修改后再次进行试运行上线。

当项目试运行过程中发现无重大问题，满足上线标准时，则项目正式上线运行，进行客户交付。

8.项目总结

当项目进行试运行上线交付后，项目经理必须召集所有项目团队成员进行项目总结会议，项目总结项目的得与失，吸取项目经验。项目文档及代码在项目的每个阶段都需要进行编写，下方会有详细的模板以及编写的要求，项目总结会议完成后，项目所有的资料，包括项目代码、项目文档、软件及硬件资料都要及时归档到公司项目库中。

下面就以某银行系统容器云平台建议的项目实战案例进行介绍。

二．项目常用管理工具

1.项目立项工具（Microsoft Office Word）

Microsoft Office Word是微软公司的一个文字处理器应用程序。Word给用户提供了用于创建专业而优雅的文档工具，帮助用户节省时间，并得到优雅美观的结果。一直以来，Microsoft Office Word都是最流行的文字处理程序。

作为Office套件的核心程序，Word提供了许多易于使用的文档创建工具，同时也提供了丰富的功能集供创建复杂的文档使用。哪怕只使用Word应用一点文本格式化操作或图片处理，也可以使简单的文档变得比只使用纯文本更具吸引力。

2.项目计划制定工具介绍（Excel）

Microsoft Excel是Microsoft为使用Windows和Apple Macintosh操作系统的电脑编写的一款电子表格软件。直观的界面、出色的计算功能和图表工具，再加上成功的市场营销，使Excel成为最流行的个人计算机数据处理软件。

 

3.系统设计工具介绍（Microsoft Office Visio）

Microsoft Office Visio是office软件系列中的负责绘制流程图和示意图的软件，是一款便于IT和商务人员就复杂信息、系统和流程进行可视化处理、分析和交流的软件。

 

4.文档代码管理工具（SVN工具使用介绍）

SVN的全称是Subversion，即版本控制系统。它是最流行的一个开放源代码的版本控制系统。作为一个开源的版本控制系统，Subversion管理着随时间改变的数据。这些数据放置在一个中央资料档案库（Repository）中。这个档案库很像一个普通的文件服务器，不过它会记住每一次文件的变动。这样就可以把档案恢复到旧的版本，或是浏览文件的变动历史。Subversion是一个通用的系统，可用来管理任何类型的文件，其中包括程序源码。

SVN采用客户端/服务器体系，项目的各种版本都存储在服务器上，程序开发人员首先将从服务器上获得一份项目的最新版本，并将其复制到本机，然后在此基础上，每个开发人员可以在自己的客户端进行独立的开发工作，并且可以随时将新代码提交给服务器。当然也可以通过更新操作获取服务器上的最新代码，从而保持与其他开发者所使用版本的一致性。

5.项目总结工具（Microsoft Office PowerPoint）

Microsoft Office PowerPoint是指微软公司的演示文稿软件，如图1-5-60所示。用户可以在投影仪或者计算机上进行演示，也可以将演示文稿打印出来，制作成胶片，以便应用到更广泛的领域中。

 

 

三．基本项目实施流程步骤

1. 创建案例目标
2. 进行案例分析
3. 项目计划
4. 案例实施
5. 项目团队成立
6. 项目立项
7. 项目立项文档

四．常用说明书

《概要设计说明书》

1引言

1.1写目的：阐明编写概要设计说明书的目的，指明读者对象。

1.2项目背景：应包括

（1）项目的委托单位、开发单位和主管部门

（2）该软件系统与其他系统的关系。

1.3定义：列出本文档中所用到的专门术语的定义和缩写词的愿意。

1.4参考资料：

（1）列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源。

（2）项目经核准的计划任务书、合同或上级机关的批文；项目开发计划；需求规格说明书；测试计划（初稿）；用户操作手册。

（3）文档所引用的资料、采用的标准或规范。

 

2任务概述

2.1目标

2.2需求概述

2.3条件与限制

 

3总体设计

3.2总体结构和模块外部设计

3.3功能分配：表明各项功能与程序结构的关系。

 

4接口设计

4.1外部接口：包括用户界面、软件接口与硬件接口。

4.2内部接口：模块之间的接口。

 

5数据结构设计

 

6逻辑结构设计 

7物理结构设计

 

8数据结构与程序的关系

 

9运行设计

9.1运行模块的组合

9.2运行控制

9.3运行时间

 

10出错处理设计

10.1出错输出信息

10.2出错处理对策：如设置后备、性能降级、恢复及再启动等。

 

11安全保密设计

 

12维护设计

说明为方便维护工作的设施，如维护模块等。

 

《详细设计说明书》

1引言

1.1编写目的：阐明编写详细设计说明书的目的，指明读者对象。

1.2项目背景：应包括项目的来源和主管部门等。

1.3定义：列出本文档中所用到的专门术语的定义和缩写词的愿意。

1.4参考资料：

（1）列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源。

（2）项目经核准的计划任务书、合同或上级机关的批文；项目开发计划；需求规格说明书；概要设计说明书；测试计划（初稿）；用户操作手册。

（3）文档所引用的资料、软件开发的标准或规范。

 

2总体设计

2.1需求概述

2.2软件结构：如给出软件系统的结构图。

 

3程序描述

3.1逐个模块给出以下说明：

（1）功能

（2）性能

（3）输入项目

（4）输出项目

3.2算法：模块所选用的算法。

3.3程序逻辑：详细描述模块实现的算法，可采用：标准流程图；PDL语言；N-S图；判定表等描述算法的图表。

3.4接口

（1）存储分配

（2）限制条件

3.5测试要点：给出测试模块的主要测试要求。

《项目立项建议书》

1 产品介绍

1.1 产品定义

提示：用简练的语言说明本产品“是什么”，“什么用途”。

1.2 产品开发背景

提示：从内因、外因两方面阐述产品开发背景，重点说明“为什么”要开发本产品。

（1）因方面着重考虑：开发方的短期、长期发展战略；开发方的当前实力。

（2）外因方面着重考虑：市场需求及发展趋势；技术状况及发展趋势。

（3）如果是合同项目，请说明项目的来源。

1.3 产品主要功能和特色

提示：

（1）给出产品的主要功能列表（Feature Lists）。

（2）说明本产品的特色。

1.4 产品范围

提示：

（1）说明本产品“适用的领域”和“不适用的领域”。

（2）说明本产品“应当包含的内容”和“不包含的内容”。

 

2 市场概述

客户需求

提示：

（1）阐述本产品面向的消费群体（客户）的特征

（2）说明客户对产品的功能性需求和非功能性需求

（3）说明本产品如何满足客户的需求，以及给客户带来什么好处。

市场规模与发展趋势

提示：

（1）分析市场发展历史与发展趋势，说明本产品处于市场的什么发展阶段。

（2）本产品和同类产品的价格分析

（3）统计当前市场的总额、竞争对手所占的份额，分析本产品能占多少份额。

注意：引用数据应当写明数据来源，最好有直观的图表。

 

3 产品发展目标

提示：说明本产品的短期目标和长期目标，目标必须清晰并且可以度量。

 

4 产品技术方案

产品体系结构

提示：

（1）绘制产品的体系结构

（2）阐述设计原理

（3）如果有多种体系结构，需比较优缺点。

4.2 关键技术

提示：阐述本产品的关键技术，评价技术实现的难易程度

 

5 产品优缺点分析

提示：综合考虑本产品的功能、质量、价格、品牌等因素，分析优缺点。

 

6 Make-or-Buy决策

提示：

确定哪些产品部件应当采购、外包开发或者自主研发，说明理由。

分析相应的风险。

 

7 项目计划

7.1 项目团队

提示：说明项目团队的角色、知识技能要求、建议人选、人数、工作时间。

7.2 软件硬件资源估计

提示：

（1）估计项目所需的软件和硬件资源，说明主要配置。

（2）说明以何种方式获得，如“已经存在”、“可以借用”或“需要购买”等。

7.3 成本估计

提示：估计项目的“人力资源成本”、“软硬件资源成本”、“商务活动成本”等等。

7.4 进度表

提示：绘制项目开发的进度表,参建附表

 

8 市场营销计划

提示：

（1）给出产品的赢利模式和价格结构。

（2）给出短期和长期销售目标。

（3）规划销售方式和渠道。

9 成本效益分析

提示：

（1）总成本是产品开发、营销、维护的成本之和；

（2）效益包括“可量化的经济效益”和“不可量化的好处”。

 

10 总结

提示：给出清晰的结论，便于上级领导决策。

《用户需求说明书》

1 引言

1.1 编写目的

本节描述编写该用户需求说明书的目的，并指出预期的读者。

1.2 项目背景

本节描述用户需求说明书中所定义的产品的背景和起源，以及同其他系统或其他机构的基本相互关系等。当在已有的系统上进行特性开发时，如果新特性与已有系统的特性之间存在关系，则应在本节说明其相互之间的关系。

1.3 术语定义

本节可列出本文件中用到的专门术语的定义、外文首字母组词的原词组等。

1.4 参考资料

本节列举编写用户需求说明书时所参考的资料或其他资源，这可能包括用户合同、公司规范、技术书籍等。在这里应该给出详细的信息，包括资料名称、版本号、作者、日期、出版单位或资料来源，以方便读者查阅这些文献，可用以下格式表示，见表1：

表1 参考资料

资料名称	版本号	作者	日期	出版单位/资料来源	备注

 

2 综合描述

2.1 产品介绍

本节简要描述产品的特性。

2.2 目标范围

本节简要描述产品的应用目标、作用范围等。

2.3 用户特性

本节可能包括本产品各类最终用户的特点，如操作、维护等人员的知识水平和技术专长

《项目计划书》电子表格（Xls）版本

 

《项目总结报告》

1引言

1.1 目的

[阐明编写本总结报告的目的和意义，指出读者对象。]

1.2 项目背景

[可包括本项目的来源、委托单位、开发单位和主管部门等。]

1.3 参考资料

2 项目基本情况

2.1项目产品

本条说明最终制成的产品，包括：

（1）源代码。列出提交的源代码版本和每个版本的功能。

（2）文档：此处列出文档清单。

（3）所建立的每个数据库。

2.2主要功能和性能

简要说明本产品所实际具有的主要功能和性能，对照项目开发计划，需求说明书的有关内容，说明原定的开发目标是达到了、未完全达到、或超过了

2.3项目进度情况（见表1）

表1项目进度情况

	实际	计划	实际天数/计划天数
项目周期
编码周期
测试周期
完成时间
计划调整次数
总体进度情况	项目实际比计划提前/拖延  天

进度与计划偏差的原因分析：

 

2.4遗留问题和风险

列出在项目开发计划的要求范围内，但尚未解决的问题以及可能遇到的风向问题。

 

3 开发工作评价

同计划相比较，给出本项目的生产效率、产品质量和技术方法的综合评价。

3.1 产品质量评价（见表2）

表2产品质量评价

	缺陷数	严重缺陷数	严重缺陷比率	缺陷密度
发布时
目标值

产品质量评价：

3.2技术方法评价

[总结该软件项目或软件产品开发时所采用的各项技术]

以下是示例：

（1）对开发工具的评价：

UBS-HotBilling使用TT作为内存数据库，提高了应用处理的性能。试点割接上线后正常运行，并且为OCS系统上线提供了实践依据，并积累了实施开发经验。

（2）对框架技术的评价：从整个框架的整体使用效果来看并为达到预期的目的，我认为主要是由以下原因造成的：

框架本身存在有诸多不完善的地方，需要不断地进行改进，但在改进的过程中没有进行严格的控制，导致框架的整体设计失控；

框架本身有这样那样的问题，有些问题是目前无法解决的；

框架是建构在PFC的基础上的，项目组成员对PFC不是足够的精通，为维护框架带来难度。

建议：模块化是产品化的基础，也是降低成本、提高开发效率保证软件质量的有效手段，需要有专人设计和维护框架。

（3）对设计方法的评价：信息化项目的整体设计是由项目组全体成员完成的，鉴于我们目前的设计水平，我看还可继续这种方法，对设计的方法和思路进行广泛的借鉴，但一定要树立设计的权威性，对设计的变更要进行严格的控制。

（4）对团队开发的评价：从整体上讲我们这个团队的能力还可以，但我认为它的生产效率并不高也就是说团队的整体建设不好，没有明确的学习方向分工，使整个团队在这段时间里整体能力没有太大的提高，我以前很想把我们的团队培养成那种学习型的优秀团队，可惜事与愿违这项工作没有取得什么实效。

 

4 项目管理工作评价

4.1需求管理

需求变更情况：不同阶段所发生的需求变更次数及发生变更的主要原因，具体见表3。

表3需求变更情况

变更发生的阶段	需求变更次数	变更工作量（从申请开始到变更结束发生的工作量）
用户需求定义
软件需求分析
设计
编码
测试
维护

需求变更的主要原因：

 

4.2 计划管理

计划变更情况，具体见表4：

表4计划变更情况

序号	变更发生阶段	变更原因	变更内容	变更是否允许
1
2
3

 

5 经验教训

5.1 项目成功经验

项目管理方面：

项目技术方面：

5.2 项目失败教训

项目管理方面：

项目技术方面：

5.3 对今后项目开发工作的建议

根据本项目的经验和教训，对于今后项目开发工作提出改进的建议。

 

《需求规格说明书》

对纯软件开发和比较大型软件开发，要求根据软件特点，由项目负责人专门进行软件需求分析，从高层次来描述系统所要解决的问题，描述用户需要怎样的产品或服务，并对实现需求目标所需采取的措施和计划进行描述。《需求说明书》可作为软件总体设计的依据，具体编写内容规范如下。

1 前言

1.1 目的

[阐明编写需求分析的目的，指明用户对象。（系统分析员、开发人员、测试人员）]

1.2 项目背景

[该软件系统与其他系统的关系。         项目的开发单位及人员。]

1.3参考资料

[列举出相关参考资料。]

 

项目概述

2.1 目标

叙述该项软件开发的意图、应用目标、作用范围。解释被开发软件与其他有关软件之间的关系。如果所定义的产品是一个更大的系统的一个组成部分，则应说明本产品与该系统中其他个组成部分之间的关系，为此可使用一张方框图来说明该系统的组成和本产品同其他各部分的联系和接口。

2.2 运行环境

2.2.1硬件设备要求（宿主机、目标机）,要描述软件系统所需的硬件设备的能力要求，如处理器的数量，内存容量，存储媒体的数量，输入，输出设备的数量，通信网络结构，网络的线路速度及通讯协议等。

2.2.2软件环境要求，要列出支持软件，包括要用到的操作系统、数据库系统、编译（或汇编）程序、测试支持软件等。

2.3 用户特性

列出本软件的最终使用者的特点，充分说明操作人员、维护人员的教育水平和技术专长，以及本软件的预期使用频度。

2.4 条件与限制

2.4.1某些既成事实的限制（硬件、软件等）

2.4.2整个大环境的情况

2.4.3某些规定的限制

 

3 性能需求

3.1 数据存储要求

确定软件的存储容量要求，如处理的记录数和处理数据的最大容量等。

3.2 管理能力的要求

3.3 时间特性

如响应时间、更新处理时间、数据转换与传输时间（误码率）、运行时间等。

3.4 适应性

在操作方式、运行环境、与其他软件接口以及开发计划等发生变化时，应具有的适应能力。

 

4 功能需求

4.1 功能划分

描述整个软件在职能上应做什么，应满足哪些功能要求

4.2 功能描述

详细描述每一条功能，用文字、图形、逻辑或数学方法描述。

 

5 数据需求

对数据进行描述时可把数据分为静态数据和动态数据。所谓静态数据，指在运行过程中主要作为参考的数据，他们在很长的一段时间内不会变化，一般不随运行而改变。所谓动态数据，包括所有在运行中要发生变化的数据以及在运行中要输入、输出的数据。

5.1 静态数据

列出所有作为控制或参考用的静态数据元素。

5.2 动态数据

列出动态输入数据元素（包括在常规运行中或联机操作中要改变的数据）。

5.3 数据约束

列出若要进一步扩充数据或更充分地使用数据，而对数据要求提出的限制（如文件、记录和数据元素的最大容量或最多个数），特别应强调在设计和开发中被确定为临界的那些约束。

5.4 数据库描述

说明为满足上述数据要求，数据库应满足的功能、性能、可靠性要求。

 

6 数据采集（根据具体软件可选）

6.1 要求和范围

6.1.1输入源：说明数据来自操作员，还是其他分系统或输入装置。

6.1.2接受者：应区分出如下种类，输入到系统，经处理后基本上无变化再输出的数据。输入到系统，但不再输出的数据。由程序生成后输出的数据。

6.1.3临界值：指出数据元素的范围，如一个转折点，临界值等。

6.1.4量纲：对数值量，应规定数据元素的增量，度量单位，测量单位的零点和值域；对于非数字量值，要用符号表示一些法定的值及他们之间的关系。

6.1.5换算因子：给出经模拟转换或数字转换处理的实测量的换算因子。

6.1.6数据更新频度：对同步数据，应给出输入，输出的更新频度，对异步数据，也要给出频度平均值或变化的某种度量。

6.2 数据采集和传递方式：

详细描述采集过程，包括数据格式，传输媒体和输入输出时间特性。

 

7 接口需求

7.1 用户接口

如屏幕格式、报表格式、菜单格式、输入输出时间等。

7.2 硬件接口

说明该软件同硬件之间的配合关系等。

7.3 软件接口

说明该软件同其他软件之间的接口、数据通信协议等。

 

8 可靠性需求

8.1余量需求

在需求分析时，应给安全关键软件留有足够余量，这些余量包括：存储量，输入输出通道的吞吐能力以及处理时间等。例如，对整个计算机系统而言，推荐的存储量，输入输出通道的吞吐能力及处理时间余量不少于20%。

8.2 故障处理要求

列出可能的软件、硬件故障以及对各项性能而言所产生的后果和对故障处理的要求

8.3 不允许发生的事件

明确列出所有在软件运行过程中绝对不允许发生的事件，如关键判别式决不允许误判等，以作为设计约束。

8.4 可靠性指标的验证（可选）

对有可靠性指标的软件，在确定了软件的功能性需求后，应考虑该软件的可靠性指标是否能达到以及是否能够验证。如果可靠性指标不能达到或者不能验证，那么，需求分析人员应向上级主管部门汇报，以期得到其他的解决方法；如果软件的可靠性指标既能达到又能验证，那么，需求分析人员应同用户密切配合，确定软件的功能剖面，并制定软件可靠性测试计划。

 

9 其他需求

如可使用性、可维护、可移植性，开发平台的需求等。