软件技术文档编写规范.doc
《软件技术文档编写规范.doc》由会员分享，可在线阅读，更多相关《软件技术文档编写规范.doc（23页珍藏版）》请在冰点文库上搜索。
目录
第一章引言1
§1.1目的1
§1.2文档约定1
§1.3预期读者和阅读建议1
§1.4产品的范围1
§1.5参考文献1
第二章综合描叙1
§2.1产品的前景1
§2.2产品的功能1
§2.3用户类和特征2
§2.4运行环境2
§2.5设计和实现上的限制2
§2.6假设和依赖2
第三章外部接口需求2
§3.1用户界面2
§3.2硬件接口3
§3.3软件接口3
§3.4通信接口3
第四章系统特性3
§4.1说明和优先级3
§4.2激励响应序列3
§4.3功能需求3
第五章其他非功能需求3
§5.1性能需求3
§5.2安全设施需求4
§5.3安全性需求4
§5.4软件质量属性4
§5.5业务规则4
§5.6用户文档4
第六章其他需求4
§6.1词汇表4
§6.2分析模型4
§6.3待确定问题列表5
第1章引言
引言提出了对软件需求规格说明的纵览，这有助于读者理解文档如何编写并且如何阅读和解释。
§1.1目的
对产品进行定义，在该文档中详尽说明了这个产品的软件需求，包括修正或发行版本号。
如果这个软件需求规格说明只与整个系统的一部分有关系，那么就只定义文档中说明的部分或子系统。
§1.2文档约定
描述编写文档时所采用的标准或排版约定，包括正文风格、提示区或重要符号。
例如，说明了高层需求的优先级是否可以被其所有细化的需求所继承，或者每个需求陈述是否都有其自身的优先级。
§1.3预期读者和阅读建议
列举了软件需求规格说明所针对的不同读者，例如开发人员、项目经理、营销人员、用户、测试人员或文档的编写人员。
描述了文档中剩余部分的内容及其组织结构。
提出了最适合于每一类型读者阅读文档的建议。
§1.4产品的范围
提供了对指定的软件及其目的的简短描述，包括利益和目标。
把软件与企业目标或业务策略相联系。
可以参考项目视图和范围文档而不是将其内容复制到这里。
§1.5参考文献
列举了编写软件需求规格说明时所参考的资料或其它资源。
这可能包括用户界面风格指导、合同、标准、系统需求规格说明、使用实例文档，或相关产品的软件需求规格说明。
在这里应该给出详细的信息，包括标题名称、作者、版本号、日期、出版单位或资料来源，以方便读者查阅这些文献。
如：
a．本项目的经核准的计划任务书或合同、上级机关的批文；
b．属于本项目的其他已发表的文件；
c．本文件中各处引用的文件、资料、包括所要用到的软件开发标准。
列出这些文件资料的标题、文件编号、发表日期和出版单位，说明能够得到这些文件资料的来源。
第2章综合描叙
这一部分概述了正在定义的产品以及它所运行的环境、使用产品的用户和已知的限制、假设和依赖。
§2.1产品的前景
描述了软件需求规格说明中所定义的产品的背景和起源。
说明了该产品是否是产品系列中的下一成员，是否是成熟产品所改进的下一代产品、是否是现有应用程序的替代品，或者是否是一个新型的、自含型产品。
如果软件需求规格说明定义了大系统的一个组成部分，那么就要说明这部分软件是怎样与整个系统相关联的，并且要定义出两者之间的接口。
§2.2产品的功能
概述了产品所具有的主要功能。
其详细内容将在d中描述，所以在此只需要概略地总结，例如用列表的方法给出。
很好地组织产品的功能，使每个读者都易于理解。
用图形表示主要的需求分组以及它们之间的联系，例如数据流程图的顶层图或类图，都是有用的。
§2.3用户类和特征
确定你觉得可能使用该产品的不同用户类并描述它们相关的特征（见第7章）。
有一些需求可能只与特定的用户类相关。
将该产品的重要用户类与那些不太重要的用户类区分开。
§2.4运行环境
描述了软件的运行环境，包括硬件平台、操作系统和版本，还有其它的软件组件或与其共存的应用程序。
§2.5设计和实现上的限制
确定影响开发人员自由选择的问题，并说明这些问题为什么成为一种限制。
可能的限制包括如下内容：
·必须使用或者避免的特定技术、工具、编程语言和数据库。
·所要求的开发规范或标准（例如，如果由客户的公司负责软件维护，就必须定义转包者所使用的设计符号表示和编码标准。
·企业策略、政府法规或工业标准。
·硬件限制，例如定时需求或存储器限制。
·数据转换格式标准。
§2.6假设和依赖
确定影响开发人员自由选择的问题，并说明这些问题为什么成为一种限制。
可能的限制包括如下内容：
·必须使用或者避免的特定技术、工具、编程语言和数据库。
·所要求的开发规范或标准（例如，如果由客户的公司负责软件维护，就必须定义转包者所使用的设计符号表示和编码标准。
·企业策略、政府法规或工业标准。
·硬件限制，例如定时需求或存储器限制。
·数据转换格式标准。
第3章外部接口需求
利用本节来确定可以保证新产品与外部组件正确连接的需求。
关联图表示了高层抽象的外部接口。
需要把对接口数据和控制组件的详细描述写入数据字典中。
如果产品的不同部分有不同的外部接口，那么应把这些外部接口的详细需求并入到这一部分的实例中。
§3.1用户界面
陈述所需要的用户界面的软件组件。
描述每个用户界面的逻辑特征。
以下是可能要包括的一些特征：
·将要采用的图形用户界面（GUI）标准或产品系列的风格。
·屏幕布局或解决方案的限制。
·将出现在每个屏幕的标准按钮、功能或导航链接（例如一个帮助按钮）。
·快捷键。
·错误信息显示标准。
对于用户界面的细节，例如特定对话框的布局，应该写入一个独立的用户界面规格说明中，而不能写入软件需求规格说明中。
§3.2硬件接口
描述系统中软件和硬件每一接口的特征。
这种描述可能包括支持的硬件类型、软硬件之间交流的数据和控制信息的性质以及所使用的通信协议。
§3.3软件接口
描述该产品与其它外部组件（由名字和版本识别）的连接，包括数据库、操作系统、工具、库和集成的商业组件。
明确并描述在软件组件之间交换数据或消息的目的。
描述所需要的服务以及内部组件通信的性质。
确定将在组件之间共享的数据。
如果必须用一种特殊的方法来实现数据共享机制，例如在多任务操作系统中的一个全局数据区，那么就必须把它定义为一种实现上的限制。
§3.4通信接口
描述与产品所使用的通信功能相关的需求，包括电子邮件、Web浏览器、网络通信标准或协议及电子表格等等。
定义了相关的消息格式。
规定通信安全或加密问题、数据传输速率和同步通信机制。
对我有用[0]丢个板砖[0]引用举报管理TOP
csdsq
（〓1〓0〓1〓0〓1〓0〓1〓）
等 级：
#6楼得分：
0回复于：
2003-04-2902:
18:
05第4章系统特性
功能需求是根据系统特性即产品所提供的主要服务来组织的。
你可能更喜欢通过使用实例、运行模式、用户类、对象类或功能等级来组织这部分内容（IEEE1998）。
你还可以使用这些元素的组合。
总而言之，你必须选择一种使读者易于理解预期产品的组织方案。
仅用简短的语句说明特性的名称，例如“4.1拼写检查和拼写字典管理”。
无论你想说明何种特性，阐述每种特性时都将重述从4.1～4.3这三步系统特性。
§4.1说明和优先级
提出了对该系统特性的简短说明并指出该特性的优先级是高、中，还是低。
或者你还可以包括对特定优先级部分的评价，例如利益、损失、费用和风险，其相对优先等级可以从1（低）到9（高）。
§4.2激励响应序列
列出输入激励（用户动作、来自外部设备的信号或其它触发器）和定义这一特性行为的系统响应序列。
就像在第8章讨论的那样，这些序列将与使用实例相关的对话元素相对应。
§4.3功能需求
详列出与该特性相关的详细功能需求。
这些是必须提交给用户的软件功能，使用户可以使用所提供的特性执行服务或者使用所指定的使用实例执行任务。
描述产品如何响应可预知的出错条件或者非法输入或动作。
就像本章开头所描述的那样，你必须唯一地标识每个需求。
第5章其他非功能需求
这部分列举出了所有非功能需求，而不是外部接口需求和限制。
§5.1性能需求
阐述了不同的应用领域对产品性能的需求，并解释它们的原理以帮助开发人员作出合理的设计选择。
确定相互合作的用户数或者所支持的操作、响应时间以及与实时系统的时间关系。
你还可以在这里定义容量需求，例如存储器和磁盘空间的需求或者存储在数据库中表的最大行数。
尽可能详细地确定性能需求。
可能需要针对每个功能需求或特性分别陈述其性能需求，而不是把它们都集中在一起陈述。
例如，“在运行微软Window2000的450MHzPentiumⅡ的计算机上，当系统至少有50%的空闲资源时，95%的目录数据库查询必须在两秒内完成”。
§5.2安全设施需求
详尽陈述与产品使用过程中可能发生的损失、破坏或危害相关的需求。
定义必须采取的安全保护或动作，还有那些预防的潜在的危险动作。
明确产品必须遵从的安全标准、策略或规则。
一个安全设施需求的范例如下：
“如果油箱的压力超过了规定的最大压力的95%，那么必须在1秒钟内终止操作”。
§5.3安全性需求
详尽陈述与系统安全性、完整性或与私人问题相关的需求，这些问题将会影响到产品的使用和产品所创建或使用的数据的保护。
定义用户身份确认或授权需求。
明确产品必须满足的安全性或保密性策略。
你可能更喜欢通过称为完整性的质量属性来阐述这些需求，完整性将在第11章介绍。
一个软件系统的安全需求的范例如下：
“每个用户在第一次登录后，必须更改他的最初登录密码。
最初的登录密码不能重用。
”
§5.4软件质量属性
详尽陈述与客户或开发人员至关重要的其它产品质量特性（见第11章）。
这些特性必须是确定、定量的并在可能时是可验证的。
至少应指明不同属性的相对侧重点，例如易用程度优于易学程度，或者可移植性优于有效性。
§5.5业务规则
列举出有关产品的所有操作规则，例如什么人在特定环境下可以进行何种操作。
这些本身不是功能需求，但它们可以暗示某些功能需求执行这些规则。
一个业务规则的范例如下：
“只有持有管理员密码的用户才能执行$100.00或更大额的退款操作。
”
§5.6用户文档
列举出将与软件一同发行的用户文档部分，例如，用户手册、在线帮助和教程。
明确所有已知的用户文档的交付格式或标准。
第6章其他需求
定义在软件需求规格说明的其它部分未出现的需求，例如国际化需求或法律上的需求。
你还可以增加有关操作、管理和维护部分来完善产品安装、配置、启动和关闭、修复和容错，以及登录和监控操作等方面的需求。
在模板中加入与你的项目相关的新部分。
如果你不需要增加其它需求，就省略这一部分。
§6.1词汇表
定义所有必要的术语，以便读者可以正确地解释软件需求规格说明，包括词头和缩写。
你可能希望为整个公司创建一张跨越多项项目的词汇表，并且只包括特定于单一项目的软件需求规格说明中的术语。
§6.2分析模型
这个可选部分包括或涉及到相关的分析模型的位置，例如数据流程图、类图、状态转换图或实体-关系图
§6.3待确定问题列表
编辑一张在软件需求规格说明中待确定问题的列表，其中每一表项都是编上号的，以便于跟踪调查。
计算机软件需求说明编制指南
1引言
1.1目的和作用
本指南为软件需求实践提供了一个规范化的方法。
本指南不提倡把软件需求说明（SoftwareRequirementsSpecifications，以下简称SRS）划分成等级，避免把它定义成更小的需求子集。
本指南适用对象：
软件客户（Customers），以便精确地描述他们想获得什么样的产品。
软件开发者（Suppliers），以便准确地理解客户需要什么样的产品。
对于任一要实现下列目标的单位和（或）个人：
a.要提出开发规范化的SRS提纲；
b.定义自己需要的具体的格式和内容；
c.产生附加的局部使用条款，如SRS质量检查清单或者SRS作者手册等。
SRS将完成下列目标：
a.在软件产品完成目标方面为客户和开发者之间建立共同协议创立一个基础。
对要实现的软件功能做全面描述，帮助客户判断所规定的软件是否符合他们的要求，或者怎样修改这种软件才能适合他们的要求；
b.提高开发效率。
编制SRS的过程将使客户在设计开始之前周密地思考全部需求，从而减少事后重新设计、重新编码和重新测试的返工活动。
在SRS中对各种需求仔细地进行复查，还可以在开发早期发现若干遗漏、错误的理解和不一致性，以便及时加以纠正；
c.为成本计价和编制计划进度提供基础。
SRS提供的对被开发软件产品的描述，是计算机软件产品成本核算的基础，并且可以为各方的要价和付费提供依据。
SRS对软件的清晰描述，有助于估计所必须的资源，并用作编制进度的依据；
d.为确认和验证提供一个基准。
任何组织将更有效地编制他们的确认和验证计划。
作为开发合同的一部分，SRS还可以提供一个可以度量和遵循的基准（然而，反之则不成立，即任一有关软件的合同都不能作为SRS。
因为这种文件几乎不包括详尽的需求说明，并且通常不完全的）；
e.便于移植。
有了SRS就便于移值软件产品，以适应新的用户或新的机种。
客户也易于移植其软件到其他部门，而开发者同样也易于把软件移植到新的客户；
f.作为不断提高的基础。
由于SRS所讨论的是软件产品，而不是开发这个产品的设计。
因此SRS是软件产品继续提高的基础。
虽然SRS也可能要改变，但是原来的SRS还是软件产品改进的可靠基础。
1.2范围
本指南适用于编写软件需求规格说明，它描述了一个SRS所必须的内容和质量，并且在第6章中提供了SRS大纲。
2引用标准
GB8566计算机软件开发规范
GB8567计算机软件产品开发文件编制指南
GB/T11457软件工程术语
3定义
GB/T11457所列术语和下列定义适用于本指南。
合同（contract）
是由客户和开发者共同签署的具有法律约束力的文件。
其中包括产品的技术、组织、成本和进度计划要求等内容。
客户（customer）
指个人或单位，他们为产品开发提供资金，通常（但有时也不必）还提出各种需求。
文件中的客户和开发者也可能是同一个组织的成员。
语言（language）
是具有语法和语义的通信工具，包括一组表达式、惯例和传递信息的有关规则。
分割（partitioning）
把一个整体分成若干部分。
开发者（supplier）
指为客户生产某种软件产品的个人或集团。
在本指南中，客户和开发者可能是同一个组织的成员。
用户（user）
指运行系统或者直接与系统发生交互作用的个人或集团。
用户和客户通常不是同一些人。
4编写SRS的背景信息
4.1SRS的基本要求
SRS是对要完成一定功能、性能的软件产品、程序或一组程序的说明。
对SRS的描述有两项基本要求：
a.必须描述一定的功能、性能；
b.必须用确定的方法叙述这些功能、性能。
4.2SRS的环境
必须认识到SRS在整个软件开发规范（见GB8566）所规定的有关阶段都起作用。
正因为如此，SRS的起草者必须特别注意不要超出这种作用的范围。
这意味着要满足下列要求：
a.SRS必须正确地定义所有的软件需求；
b.除了设计上的特殊限制之外，SRS中一般不描述任何设计、验证或项目管理细节。
4.3SRS的特点
4.3.1无歧义性
当且仅当它对每一个需求只有一种解释时，SRS者是无歧义的。
a.要求最终产品的每一个特性用某一术语描述；
b.若某一术语在某一特殊的行文中使用时具有多种歧义，那么对该术语的每种含义作出解释并指出其适用场合。
需求通常是用自然语言编写的，使用自然语言的SRS起草者必须特别注意消除其需求的歧义性。
提倡使用形式化需求说明语言。
4.3.2完整性
如果一个SRS能满足下列要求，则该SRS就是完整的：
a.包括全部有意义的要求，无论是关系到功能的、性能的、设计约束的，还是关系到属性或外部接口方面的需求；
b.对所有可能出现的输入数据的响应予以定义，要对合法和非合法的输入值的响应做出规定；
c.要符合SRS要求。
如果个别章节不适用，则在SRS中要保留章节号；
d.填写SRS中的全部插图、表、图示标记和参照，并且定义全部术语和度量单位。
4.3.2.1关于使用“待定”一词的规定
任何一个使用“待定”的SRS都是不完全的。
a.若万一遇到使用“待定”一词时，作如下处理：
（1）对产生“待定”一词的条件进行描述，使得问题能被解决；
（2）描述必须干什么事，以删除这个“待定”；
b.包含有“待定”一词的任何SRS的项目文件应该：
（1）标识与此特定文件有关的版本号或叙述其专门的发布号；
（2）拒绝任何仍标识为“待定”一词的SRS章节的许诺。
4.3.3可验证性
当且仅当SRS中描述的每一个需求都是可以验证的，该SRS才是可以验证的；当且仅当在某一性能价格比可取的有限处理过程，人或机器能通过该过程检查软件产品能否满足需求时，才称这个需求是可以验证的。
4.3.4一致性
当且仅当SRS中各个需求的描述是不矛盾时SRS才是一致的。
4.3.5可修改性
如果一个SRS的结构和风格在需求有必要改变时是易于实现的、完整性的、一致的，那么这个SRS就是可以修改的。
可修改性要求SRS具备以下条件：
a.具有一个有条不紊的易于使用的内容组织，具有目录表，索引和明确的交叉引用表；
b.没有冗余。
即同一需求不能在SRS中出现多次。
（1）冗余本身不是错误，但是容易发生错误。
冗余可增加SRS的可读性，但是在一个冗余文件被更新时容易出现问题。
例如：
假设一个明确的需求在两个地方详细列出，后来发现这个需求需要改变，若只修改一个地方，于是SRS就变得不一致了。
（2）不管冗余是否必须，SRS一定要包含一个详细的交叉引用表，以便SRS具备可修改性。
4.3.6可追踪性
如果每一个需求的源流是清晰的，在进一步产生和改变文件编制时，可以方便地引证每一个需求，则该SRS就是可追踪的。
建议采用如下两种类型的追踪：
a.向后追踪（即向已开发过的前一阶段追踪）。
根据先前文件或本文件前面的每一个需求进行追踪。
b.向前追踪（即是向由SRS派生的所有文件追踪）。
根据SRS中具有唯一的名字和参照号的每一个需求进行追踪。
当SRS中的一个需求表达另一个需求的一种指派或者是派生的，向前、向后的追踪都要提供。
例如：
（1）从总的用户响应时间需求中分配给数据库操作响应时间；
（2）识别带有一定功能和用户接口的需求的报告格式；
（3）支持法律或行政上需要的某个软件产品（例如，计算税收）。
在这种情况下，要指出软件所支持的确切的法律或行政文件。
当软件产品进入运行和维护阶段时，SRS的向前可追踪性显得特别重要。
当编码和设计文件作修改时，重要的是要查清这些修改所影响的全部需求。
4.3.7运行和维护阶段的可使用性
SRS必须满足运行和维护阶段的需要，包括软件最终替换。
a.维护常常是由与原来开发无联系的人来进行的。
局部的改变（修正）可以借助于好的代码注释来实现。
对于较大范围的改变。
设计和需求文件是必不可少的，这里隐含了两个作用：
（1）如4.3.5条指出，SRS必须是可修改的；
（2）SRS中必须包括一个记录，它记录那些应用于各个成分的所有具体条文。
例如：
它们的危急性（如故障可能危及完全或导致大量财政方面和社会方面的损失）；
它们仅与暂时的需要相关（如支持一种可立即恢复原状的显示）；
它们的来源（如某功能是由已存在的软件产品的全部拷贝复制而成）。
b.要求在SRS中清楚地写明功能的来源和目的，因为对功能的来源和引入该功能的目的不清楚的话，通常不可能很好地完成软件的维护。
4.4SRS的编制者
软件开发的过程是由开发者和客户双方同意开发什么样的软件协议开始的。
这种协议要使用SRS的形式，应该由双方联合起草。
这是因为：
a.客户通常对软件设计和开发过程了解较少，而不能写出可用的SRS；
b.开发者通常对于客户的问题和意图了解较少，从而不可能写出一个令人满意的系统需求。
4.5SRS的改进
软件产品的开发过程中，在项目的开始阶段不可能详细说明某些细节，在开发过程中可能发现SRS的缺陷、缺点和错误之类的问题，所以可能要对SRS进行改进。
在SRS的改进中，应注意如下事项：
4.5.1尽管可以预见校正版本的开发以后不可避免，而对需求还必须尽可能完全、清楚地描述。
4.5.2一旦最初识别出项目的变化，应引入一个正式的改变规程来标识、控制、追踪和报告项目的改变。
批准了的需求改变，用如下的方法编入SRS之中：
a.提供各种改变后的正确的、完全的审查记录；
b.允许对SRS当前的和被替代部分的审查。
SRS的编制工具
编制SRS最显而易见的方法是用自然语言来描述。
尽管自然语言是丰富多彩的，但不易精确，用形式化的方法较好。
4.6.1形式化说明方法
在SRS中是否使用形式化方法要依据下列因素：
a.程序规模和复杂性；
b.客户合同中是否要求使用；
c.SRS是否是一个合同工具或仅仅是一个内部文件；
d.SRS文件是否成为设计文
升级会员 