技术文档规范建议

技术文档规范建议

一个软件能否顺利的完成并且功能是否完善，重要是看这个软件有多少文档，软件开发文档是一个软件的支柱，如果开发文档漏洞百出，那么开发出来的软件也不可能会好；开发文档的好坏可以直接影响到所开发出来软件的成功与否。

----开发----

功能要求文档（首次接触客户、记录客户需求、整理简单的说明文档）

来源于客户要求和市场调查，是软件开发中最早期的一个环节。客户提出一个模糊的功能概念，或者要求解决一个实际问题，或者参照同类软件的一个功能。有软件经验的客户还会提供比较详细的技术规范书，把他们的要求全部列表书写在文档中，必要时加以图表解说。这份文档是需求分析的基础。

投标方案（根据需求是否起草）

根据用户的功能要求，经过与招标方沟通和确认，技术人员开始书写《投标方案》，方案书一般包括以下几个重要的章节：前言-- 项目背景、公司背景和业务、技术人员结构、公司的成功案例介绍等。需求分析-- 项目要求、软件结构、功能列表、功能描述、注意事项等。技术方案-- 总体要求和指导思想、技术解决方案、软件开发平台、网络结构体系等。项目管理-- 描述公司的软件开发流程、工程实施服务、组织和人员分工、开发进度控制、软件质量保证、项目验收和人员培训、软件资料文档等。技术支持-- 公司的技术支持和服务介绍、服务宗旨和目标、服务级别和响应时间、技术服务区域、技术服务期限、授权用户联系人等。系统报价-- 软、硬件平台报价列表、软件开发费用、系统维护费用等。项目进度-- 整个项目的进度计划，包括签署合同、项目启动、需求分析、系统分析、程序开发、测试维护、系统集成、用户验收、用户培训等步骤的时间规划。

需求分析（方案书）

包括产品概述、主要概念、操作流程、功能列表和解说、注意事项、系统环境等。以《功能要求》为基础，进行详细的功能分析( 包括客户提出的要求和根据开发经验建议的功能) ，列出本产品是什么，有什么特殊的概念，包括哪些功能分类，需要具备什么功能，该功能的操作如何，实现的时候该注意什么细节，客户有什么要求，系统运行环境的要求等。这里的功能描述跟以后的使用手册是一致的。通俗的讲，对用户的意图不断揭示和验叛的过程，要对经过系统可行性分析所确定的系统目标做更为详细的描述。

1.准确的理解和描述客户需要的功能。

2.帮助客户挖掘需求。

3.分析客户需求的可行性。.

项目设计（系统分析、系统设计、数据库设计）

系统分析包括技术选型、技术比较、开发人员、关键技术问题的解决、技术风险、技术升级方向、技术方案评价，竞争对手技术分析等。以《需求分析》为基础，进行详细的技术分析( 产品的性能和实现方法) ，列出本项目需要使用什么技术方案，为什么，有哪些技术问题要解决，估计开发期间会碰到什么困难，技术方案以后如何升级，对本项目的技术有什么评价等。

系统设计包括功能实现、模块组成、功能流程图、函数接口、数据字典、软件开发需要考虑的各种问题等。以《需求分析》为基础，进行详细的系统分析( 产品的开发和实现方法) ，估计开发期间需要把什么问题说明白，程序员根据《系统分析》，以系统设计为

基础开始在项目主管的带领下进行编码。

数据库设计包括设计数据库名称、表名、字段名、字段类型、字段说明、备注、字段数值计算公式等。以《系统设计》为基础，进行详细的数据库设计。必要时可以用图表解说，特别是关系数据库。

界面文档（UI设计）

包括软件外观、界面素材、编辑工具、文件名、菜单、按钮和其它界面部件的要求，这里与软件完成后的运行界面是一致的。

系统测试（单元测试、集成测试、测试文档）

通过开发人员使用的最新版本的的需求分析文档、项目设计文档进行单元测试、集成测试；测试内容包括，恢复测试、性能测试、安全测设、强度测试、整理对应测试结果反馈文档。

系统部署（编译手册、系统部署、数据初始化、用户培训/并行/试运行）

编译手册包括服务器编译环境、操作系统、编译工具、目录说明、程序生成、源程序文件列表。客户端的编译过程、编译结果、编译示例、编译环境、操作系统、编译工具、源文件列表和制作安装程序的过程。

作系统部署安装、数据初始化、用户培训文档详细记录，包括系统环境、运行平台、产品安装过程、初始环境设置、安装记录等。

----产品----

产品演示（PPT演示+功能介绍）

包括公司简介、产品背景、产品描述、产品特点、产品作用、适用范围、使用分析、功能模块、解决问题、合作伙伴、成功案例等。一般用Power point 或者VCD 录制软件实现。

报价规则（平台开发、第三方软硬件集成、服务器、维护、其他）

1. 平台开发价格估算方式-软件开发价格与工作量、商务成本、国家税收和企业利润等项有关；工期与工作经验值、风险系数和复用系数有关建议制定一个计算公式：软件开发价格=工期*人员*人员成本（元/人/天）

详见软件开发报价和报价模板的计算方法

疑问解答（客服人员、开发人员）

列出用户关心的问题和处理方法。用于解答软件的操作功能和解决用户的疑难问题。功能介绍（公司案例记录）

以需求分析为书写基础，包括软件介绍、软件结构、功能列表、功能描述和公司联系地址。

使用手册（根据客户需求书写对应手册母版）

包括产品简介、功能列表、功能描述和解释、功能操作、客户服务和联系方式等。

----技术----

编程规范

开发适用、规范、安全、稳定、灵活的基础层代码架构

代码文档规范

基于编程规范书写代码文档、统一代码文档格式、内容；例如接口文档、功能函数文档等

版本控制规范

通过局域网、服务器的版本控制器SVN、Git等版本控制工具实现代码整合、分离、检出、导入、迁移、维护

代码备份规范

定期在Serv-U 等FTP服务器备份可执行源代码、编译文件、进度说明、数据库；以及其他电子纸质文档资料。

----维护----

服务器维护

服务器日常稳定运行的监听、各类组件、防火墙、中间件的安装以及维护，以及应对突发性问题的的补救应急的预备方案、措施的建立。

项目维护

平台、系统的日常监听、修复、完善、微调以及上线运行后的运行控制。

安全维护

包括网络安全、项目安全、数据安全在内的日常信息安全防护以及，补救应急的预备方案、措施的建立

----技术文档命名规范----

版本号命名规则（移动端/PC端）

版本号是用来识别当前版本唯一性的命名方式

标准的版本号采用VX.Y.Z 的格式。例如V5.3.2

其中V表示版本号：version number ，简写为V；

X、Y、Z 为非负的整数。X 是主版本号、Y 是次版本号、Z 为修订号。

首次发布的版本命名为v1.0.0。后期每更新一个版本，就在版本号上+1。

更新规则：

1.当修改Bug和优化功能时，修改叠加第三位数字，即Z+1.其他不变。例如：v1.0.0——V1.0.1。

2.当新增小功能时，修改叠加第二位数次，即Y+1.其他不变。例如：v1.0.0——V1.1.0。

3.当新增大功能或者对原有功能有大改动时，修改叠加第一位数次，即X+1.其他不变。例如：v1.0.0——V2.0.0。

4.前面的位数叠加后，后面的位数从零开始计算。

技术文档命名规则

格式：XXX-BB-VN.N.N-(YYMMDD)

XXX：项目名称（企业信息管理系统）

BB：文档类型（需求分析）

N.N.N：版本号（1.0.1）

YYMMDD：年月日

例：企业信息管理系统-需求分析-V1.0.1-(190122)

----日常文档管理----

历史文档管理

历史文档的电子版分类管理、存储、调阅；通过内部OA管理系统建立电子文档管理