华为需求与设计工程文档写作(含模版)
合集下载
相关主题
- 1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
- 2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
- 3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。
需求设计写作培训
质量管理部 SQA小组 2005.06
课程范围
仅关注如何写作文档 不涉及具体的需求分析和设计方法
课程内容
为什么要文档化
文档写作基本要求
需求设计文档模板 需求文档写作
设计文档写作
为什么要文档化
开发人员通过文档化的过程查错补遗； 便于评审，在早期发现技术上的问题； 后续阶段开发任务可能由他人承担，输 出文档便于他们开展工作； 维护人员开展维护工作需要； 文档是必要的交付件； …………
何处获取
http://jvpal http://jvpal http://jvpal http://jvpal http://jvpal http://jvpal \\h3crnd01-fs\软件 部规范\小特性开发规 范\模板\需求设计
需求设 计合一
19ቤተ መጻሕፍቲ ባይዱ
来自华为北研所
课程内容
为什么要文档化
文档写作基本要求
修改成如下的描述呢？
………… 1.使用时间芯片的LSW（支持记录时间功能），利用设备时间戳特性可以 检测出设备是否重启，设备重启时将CAMS上的在线用户删除，并依据最后一次计费 更新报文终结计费。用户可再次正常登陆。
练习
由于一台设备可以设置多个radius服务器，也就是 radius scheme。用户可以通过命令行来配置该radius服务 器是否启动设备重启防吊死功能。
可 读 性 就 尤 为 关 键
为什么要文档化
―所有的过程分析都要形成文档。我们现在有一个严重的问题是，大 家好像不喜欢写文档，对于需要的实现方案，通常都是一个负责人在脑 袋里想想该怎么实现，然后邮件或电话找几个相关人员讨论一下就算可 以了，可能连个会议材料或会议纪要都没有。 而老外可不是这样的，他们非常非常重视文档，他们认为一个人在 脑袋里想的东西是不清晰也不全面的，有时候心里想的认为很正确的方 案实际上可能存在致命缺陷。他们要求必须把心里的想法形成文档才能 有效的避免这种问题。写文档的过程中，可以更加有效的、更进一步去 整理您原来心里的思路，很多问题在您写过文档的过程中您就能发现； 另外，文档写作多使用图表，浪费口水的文字尽量少用，和我们一起工 作的系统工程师在系统架构分析中就画了五六十张图，就算看不懂他写 的英文，从图中我们就能够很清晰的指导整个产品的系统架构。” —— 摘自一位华为员工的瑞典出差报告
需求设计文档模板 需求文档写作
设计文档写作
什么是好的需求
完整性
清晰性
什么样的 需求是好 的需求
可验证性
一致性
可行性
练习
大家看看下面的需求描述如何？
2.1.1Functional Requirements1 功能需求1修改设置smarton password命令 1. Introduction介绍 在设置smarton password的同时，规定密码显示形式为明文和密文。 2. Inputs 输入 1)密码显示形式。 2)smarton password。 3. Process 处理 1)记录密码显示形式。 2)当密码显示形式为simple时，直接设置smarton password为设置值；当密码显示形式为 cipher时，如果设置值是密文，先将其进行解密成明文再设置，如果是明文则直接设置。 4. output输出 1.介绍中描述的显示形式有明文和 无 密文两种，但处理中描述的显示形 5. Inherit继承性 式却是simple和cipher，不一致； Update-需要改进
练习
2.1.1 SRS.FUNC.DHG.001 IKE模块支持DH交换时使用Group5， Group14 1.Introduction介绍 支持IKE DH组的Group5和Group14是由8040波兰提出的新需求，用户 希望能提供更高安全级别的安全密钥，希望能支持DH 3/4/5，但是DH Group3/4是由椭圆曲线来实现的，与Group1/2/5有很大的区别，且需 要较大的工作量，因此本次特性开发暂且实现对Group5/14的支持。 完整性：这种术语也应 该简单介绍，毕竟 不是算数学题
练习
西
再改成如下图形描述呢？
北
阳台
客厅
餐厅
卫生间
次卧室
过道 书房
主卧室
门厅
厨房
阳台
练习
下面的描述呢？ 白话
LSW与CAMS配合实现认证计费的方案中，客户（禁止多人同时使用的业务 帐号）登陆通过认证开始计费后，如果出现LSW重起的情况，处理方法分为两种： 1.有时间芯片的LSW（可以记录时间的），设备重起后会使用设备时间戳 的特性判断出设备重起了，这时会将CAMS上的在线用户删除并按照最后一次计费更 新报文来终结计费。用户可再次正常登陆。 2.……
5
课程内容
为什么要文档化
文档写作基本要求
需求设计文档模板 需求文档写作
设计文档写作
文档写作基本要求
下面的文档出自于我们开发人员的手笔，大家 觉得如何？
文档写作基本要求
应使用标准模板写作； 文档封页、页眉页脚、修订记录、附录、参考文 献应完善； 关键词、摘要、缩略语应完整； 目录要及时更新； 通篇文档标题、文字格式、间距应协调美观； 所有文档模板中的章节，只可增加，不可删除； 编写建议是用来指导文档写作的，在利用完后要 及时删除； 图号置于图形之下，表号置于表格之上；
总体概述
软件概述 软件功能 用户特征 假设和依赖关系
软件质量属性
可维护性 可靠性 ……
需求建模
建模工具
具体需求
功能需求 性能需求 外部接口需求
依赖关系 其他需求 需求分级 附录
简介
简介
总体 概述
具体 需求
设计 约束
大段的叙述， 不利于理解！
10
练习
修改成如下描述之后呢？
1.房子南北走向，房子大门在东侧中间位置。 2.门厅长3米，宽2米，门厅左面是主卧室，右面是厨房。 3.厨房3米宽，4米长，厨房门对着门厅，厨房的顶头还有一个北阳台，与 厨房同宽，长1米。 4.主卧室宽3米，长5米左右，房间门对着客厅。 5.客厅与餐厅连为一体，共7米长，4米宽，与客厅相连有一南阳台，与客 厅同宽，长1.5米。 6.餐厅的北面是卫生间，卫生间与厨房相对，中间由1米宽，3米长的过道 隔开；卫生间门对着过道，南墙与厨房的南墙在一条直线上；卫生间为 长方形，南墙长3米，另一边长2米。 7.卫生间的北面是次卧，同宽，门朝着过道，次卧长4米。 8.过道的北端是书房门，书房南北长4米，书房有一个一米见方的门厅， 书房的西墙长4米，包括1米长的门厅长度，西墙把书房和次卧分隔开。 门厅东墙北端90角折向东，长2米，把书房和厨房北阳台分隔开。
CAMS收到该报文后会立即回应一个code=5的计费回应 报文，然后根据accounting-on报文携带的NAS-IP和NAS-ID 找到通过该设备认证的用户，并将其在线信息删除。
15
练习
修改原因： 这个函数是将要发送的packet转化为buffer，系统原有函数 RD_PutPacketToBuffer是针对认证用户设计的，由于本特性为设备启动 后执行，没有用户信息，所以在RD_PutPacketToBuffer函数基础上做了 一些修改，形成该函数。
由于一台设备可以设置多个radius服务器，即radius scheme。用户可以通过命令行来配置该radius服务器是否 启动设备重启防吊死功能。
练习
CAMS收到该报文后会立即回应一个code=5的计费回应 报文，然后根据accounting-on报文携带的NAS-IP和NAS-ID 找到通过该设备认证的用户，并将他们的在线信息删除。
3. “DHCP server就是这样的一个模块”，是否相关？
课程内容
为什么要文档化
文档写作基本要求
需求设计文档模板 需求文档写作
设计文档写作
需求设计文档模板
模板
需求 设计
SRS文档：REP01T01 接口文档：REP01T03 概要设计：DVP05T01 详细设计：DVP05T03 软件设计：DVP05T04 移植设计：DVP05T05
2.密码允许输入哪些字符，长度有 无限制，均没有交待。不完整 3.输出没有吗？不完整
练习
2.1.1配置或者取消配置系统WOL功能 1. Introduction介绍 在系统视图下配置或者取消配置WOL使能。 在前面没有介绍的情 况下，这里应对缩略 2. Inputs 输入 语进行详细解释，否 系统视图下: 则不完整 wol enable 或 undo wol enable 3. Process 处理 在系统视图下配置或者取消WOL使能。去系统WOL使能时，将WOL模块的MACADDR表清空，释放所占内存。初始化MAC地址表相关指针。 4. output输出 WOL功能在系统中被使能或被去使能；去系统使能时，MAC-ADDR表被清空。 5. Inherit继承性 NEW-新增功能
修改原因： 该函数实现将待发送的packet转化为buffer的功能，系统原有函数 RD_PutPacketToBuffer针对认证用户设计，由于本特性为设备启动后执 行，没有用户信息，所以在RD_PutPacketToBuffer函数基础上做了一些 修改，形成该函数。
练习
ARP Authorized加强了网络安全，阻止了DHCP server对非法ARP回应 进行学习，并且通过周期的ARP ping可以快速的探测到用户是否下线。 在设备的接口上使能ARP Authorized，该接口的ARP动态学习功能被 禁止。在某个接口上禁止arp动态学习，不影响其他接口的arp学习。 在禁止了arp动态学习的接口上，只能通过手工添加静态arp，或者其 他一些被允许的模块才可以添加arp，这种arp被称为ARP Authorized， 授权arp不再和其他的动态表项一样老化，而是有自己的老化机制，后面 会说明。DHCP server就是这样的一个模块。 静态arp的优先级高于授权arp，也就是说可以覆盖授权arp。 1. ARP与arp、ARP Authorized与授权arp，使用术语 应该统一； 2. ARP Authorized应先解释后引用；
文档写作基本要求
应追求图文并茂的效果； 句子和段落要短； 使用语言应严谨，不要使用白话； 采用主动语气； 不要出现“我们”、“你们”、“他们”这样的 称谓，或“这个”、“那个”这样的词，应使用 “本××‖、“该××‖、“其”； 表述清晰，避免引起歧义； 通篇文档细节上要保持一致；
练习
大家认为下面的描述如何？
是左？ 还是右？
究竟长多 少？?
房子南北走向，房子大门在东侧中间位置。门厅长约3米， 宽2米，门厅左面是主卧室，右面是厨房。厨房3米宽，4米长， 厨房门对着门厅，厨房的顶头还有一个北阳台，与厨房同宽， 长1米。主卧室宽3米，长5米左右，房间门对着客厅。客厅与餐 厅连为一体，共7米长，4米宽，与客厅相连有一南阳台，与客 厅同宽，长1.5米。餐厅的北面是卫生间，卫生间与厨房相对， 中间由1米宽，3米长的过道隔开；卫生间门对着过道，南墙与 厨房的南墙在一条直线上；卫生间为长方形，南墙长3米，另一 边长2米。卫生间的北面是次卧，同宽，门朝着过道，次卧长4 米。过道的北端是书房门，书房南北长4米，书房有一个一米见 方的门厅，书房的西墙长4米，包括1米长的门厅长度，西墙把 书房和次卧分隔开。门厅东墙北端90角折向东，长2米，把书房 和厨房北阳台分隔开。
练习
2.2.18 R.FUNC. 018支持XRN堆叠 …… 3.Process 处理 当unit down时，处理端口删除消息，把down掉的unit端口从镜像组中 删除，由此可能有相应的镜像组状态的改变。 当收到unit up消息时，本unit向其它unit发送端口镜像同步消息。此 消息包含本unit所配置的镜像组信息。
―可能”、“流畅”都是不 2.2.1 Performance Requirements 性能需求 清晰的，不同人理解不一 1. Performance Requirements1 性能需求1 样。 通话语音要求流畅。 不清晰一般也不可验证。
25
SRS大纲
简介
目的 范围
总体设计约束
标准符合性 硬件约束 技术限制
质量管理部 SQA小组 2005.06
课程范围
仅关注如何写作文档 不涉及具体的需求分析和设计方法
课程内容
为什么要文档化
文档写作基本要求
需求设计文档模板 需求文档写作
设计文档写作
为什么要文档化
开发人员通过文档化的过程查错补遗； 便于评审，在早期发现技术上的问题； 后续阶段开发任务可能由他人承担，输 出文档便于他们开展工作； 维护人员开展维护工作需要； 文档是必要的交付件； …………
何处获取
http://jvpal http://jvpal http://jvpal http://jvpal http://jvpal http://jvpal \\h3crnd01-fs\软件 部规范\小特性开发规 范\模板\需求设计
需求设 计合一
19ቤተ መጻሕፍቲ ባይዱ
来自华为北研所
课程内容
为什么要文档化
文档写作基本要求
修改成如下的描述呢？
………… 1.使用时间芯片的LSW（支持记录时间功能），利用设备时间戳特性可以 检测出设备是否重启，设备重启时将CAMS上的在线用户删除，并依据最后一次计费 更新报文终结计费。用户可再次正常登陆。
练习
由于一台设备可以设置多个radius服务器，也就是 radius scheme。用户可以通过命令行来配置该radius服务 器是否启动设备重启防吊死功能。
可 读 性 就 尤 为 关 键
为什么要文档化
―所有的过程分析都要形成文档。我们现在有一个严重的问题是，大 家好像不喜欢写文档，对于需要的实现方案，通常都是一个负责人在脑 袋里想想该怎么实现，然后邮件或电话找几个相关人员讨论一下就算可 以了，可能连个会议材料或会议纪要都没有。 而老外可不是这样的，他们非常非常重视文档，他们认为一个人在 脑袋里想的东西是不清晰也不全面的，有时候心里想的认为很正确的方 案实际上可能存在致命缺陷。他们要求必须把心里的想法形成文档才能 有效的避免这种问题。写文档的过程中，可以更加有效的、更进一步去 整理您原来心里的思路，很多问题在您写过文档的过程中您就能发现； 另外，文档写作多使用图表，浪费口水的文字尽量少用，和我们一起工 作的系统工程师在系统架构分析中就画了五六十张图，就算看不懂他写 的英文，从图中我们就能够很清晰的指导整个产品的系统架构。” —— 摘自一位华为员工的瑞典出差报告
需求设计文档模板 需求文档写作
设计文档写作
什么是好的需求
完整性
清晰性
什么样的 需求是好 的需求
可验证性
一致性
可行性
练习
大家看看下面的需求描述如何？
2.1.1Functional Requirements1 功能需求1修改设置smarton password命令 1. Introduction介绍 在设置smarton password的同时，规定密码显示形式为明文和密文。 2. Inputs 输入 1)密码显示形式。 2)smarton password。 3. Process 处理 1)记录密码显示形式。 2)当密码显示形式为simple时，直接设置smarton password为设置值；当密码显示形式为 cipher时，如果设置值是密文，先将其进行解密成明文再设置，如果是明文则直接设置。 4. output输出 1.介绍中描述的显示形式有明文和 无 密文两种，但处理中描述的显示形 5. Inherit继承性 式却是simple和cipher，不一致； Update-需要改进
练习
2.1.1 SRS.FUNC.DHG.001 IKE模块支持DH交换时使用Group5， Group14 1.Introduction介绍 支持IKE DH组的Group5和Group14是由8040波兰提出的新需求，用户 希望能提供更高安全级别的安全密钥，希望能支持DH 3/4/5，但是DH Group3/4是由椭圆曲线来实现的，与Group1/2/5有很大的区别，且需 要较大的工作量，因此本次特性开发暂且实现对Group5/14的支持。 完整性：这种术语也应 该简单介绍，毕竟 不是算数学题
练习
西
再改成如下图形描述呢？
北
阳台
客厅
餐厅
卫生间
次卧室
过道 书房
主卧室
门厅
厨房
阳台
练习
下面的描述呢？ 白话
LSW与CAMS配合实现认证计费的方案中，客户（禁止多人同时使用的业务 帐号）登陆通过认证开始计费后，如果出现LSW重起的情况，处理方法分为两种： 1.有时间芯片的LSW（可以记录时间的），设备重起后会使用设备时间戳 的特性判断出设备重起了，这时会将CAMS上的在线用户删除并按照最后一次计费更 新报文来终结计费。用户可再次正常登陆。 2.……
5
课程内容
为什么要文档化
文档写作基本要求
需求设计文档模板 需求文档写作
设计文档写作
文档写作基本要求
下面的文档出自于我们开发人员的手笔，大家 觉得如何？
文档写作基本要求
应使用标准模板写作； 文档封页、页眉页脚、修订记录、附录、参考文 献应完善； 关键词、摘要、缩略语应完整； 目录要及时更新； 通篇文档标题、文字格式、间距应协调美观； 所有文档模板中的章节，只可增加，不可删除； 编写建议是用来指导文档写作的，在利用完后要 及时删除； 图号置于图形之下，表号置于表格之上；
总体概述
软件概述 软件功能 用户特征 假设和依赖关系
软件质量属性
可维护性 可靠性 ……
需求建模
建模工具
具体需求
功能需求 性能需求 外部接口需求
依赖关系 其他需求 需求分级 附录
简介
简介
总体 概述
具体 需求
设计 约束
大段的叙述， 不利于理解！
10
练习
修改成如下描述之后呢？
1.房子南北走向，房子大门在东侧中间位置。 2.门厅长3米，宽2米，门厅左面是主卧室，右面是厨房。 3.厨房3米宽，4米长，厨房门对着门厅，厨房的顶头还有一个北阳台，与 厨房同宽，长1米。 4.主卧室宽3米，长5米左右，房间门对着客厅。 5.客厅与餐厅连为一体，共7米长，4米宽，与客厅相连有一南阳台，与客 厅同宽，长1.5米。 6.餐厅的北面是卫生间，卫生间与厨房相对，中间由1米宽，3米长的过道 隔开；卫生间门对着过道，南墙与厨房的南墙在一条直线上；卫生间为 长方形，南墙长3米，另一边长2米。 7.卫生间的北面是次卧，同宽，门朝着过道，次卧长4米。 8.过道的北端是书房门，书房南北长4米，书房有一个一米见方的门厅， 书房的西墙长4米，包括1米长的门厅长度，西墙把书房和次卧分隔开。 门厅东墙北端90角折向东，长2米，把书房和厨房北阳台分隔开。
CAMS收到该报文后会立即回应一个code=5的计费回应 报文，然后根据accounting-on报文携带的NAS-IP和NAS-ID 找到通过该设备认证的用户，并将其在线信息删除。
15
练习
修改原因： 这个函数是将要发送的packet转化为buffer，系统原有函数 RD_PutPacketToBuffer是针对认证用户设计的，由于本特性为设备启动 后执行，没有用户信息，所以在RD_PutPacketToBuffer函数基础上做了 一些修改，形成该函数。
由于一台设备可以设置多个radius服务器，即radius scheme。用户可以通过命令行来配置该radius服务器是否 启动设备重启防吊死功能。
练习
CAMS收到该报文后会立即回应一个code=5的计费回应 报文，然后根据accounting-on报文携带的NAS-IP和NAS-ID 找到通过该设备认证的用户，并将他们的在线信息删除。
3. “DHCP server就是这样的一个模块”，是否相关？
课程内容
为什么要文档化
文档写作基本要求
需求设计文档模板 需求文档写作
设计文档写作
需求设计文档模板
模板
需求 设计
SRS文档：REP01T01 接口文档：REP01T03 概要设计：DVP05T01 详细设计：DVP05T03 软件设计：DVP05T04 移植设计：DVP05T05
2.密码允许输入哪些字符，长度有 无限制，均没有交待。不完整 3.输出没有吗？不完整
练习
2.1.1配置或者取消配置系统WOL功能 1. Introduction介绍 在系统视图下配置或者取消配置WOL使能。 在前面没有介绍的情 况下，这里应对缩略 2. Inputs 输入 语进行详细解释，否 系统视图下: 则不完整 wol enable 或 undo wol enable 3. Process 处理 在系统视图下配置或者取消WOL使能。去系统WOL使能时，将WOL模块的MACADDR表清空，释放所占内存。初始化MAC地址表相关指针。 4. output输出 WOL功能在系统中被使能或被去使能；去系统使能时，MAC-ADDR表被清空。 5. Inherit继承性 NEW-新增功能
修改原因： 该函数实现将待发送的packet转化为buffer的功能，系统原有函数 RD_PutPacketToBuffer针对认证用户设计，由于本特性为设备启动后执 行，没有用户信息，所以在RD_PutPacketToBuffer函数基础上做了一些 修改，形成该函数。
练习
ARP Authorized加强了网络安全，阻止了DHCP server对非法ARP回应 进行学习，并且通过周期的ARP ping可以快速的探测到用户是否下线。 在设备的接口上使能ARP Authorized，该接口的ARP动态学习功能被 禁止。在某个接口上禁止arp动态学习，不影响其他接口的arp学习。 在禁止了arp动态学习的接口上，只能通过手工添加静态arp，或者其 他一些被允许的模块才可以添加arp，这种arp被称为ARP Authorized， 授权arp不再和其他的动态表项一样老化，而是有自己的老化机制，后面 会说明。DHCP server就是这样的一个模块。 静态arp的优先级高于授权arp，也就是说可以覆盖授权arp。 1. ARP与arp、ARP Authorized与授权arp，使用术语 应该统一； 2. ARP Authorized应先解释后引用；
文档写作基本要求
应追求图文并茂的效果； 句子和段落要短； 使用语言应严谨，不要使用白话； 采用主动语气； 不要出现“我们”、“你们”、“他们”这样的 称谓，或“这个”、“那个”这样的词，应使用 “本××‖、“该××‖、“其”； 表述清晰，避免引起歧义； 通篇文档细节上要保持一致；
练习
大家认为下面的描述如何？
是左？ 还是右？
究竟长多 少？?
房子南北走向，房子大门在东侧中间位置。门厅长约3米， 宽2米，门厅左面是主卧室，右面是厨房。厨房3米宽，4米长， 厨房门对着门厅，厨房的顶头还有一个北阳台，与厨房同宽， 长1米。主卧室宽3米，长5米左右，房间门对着客厅。客厅与餐 厅连为一体，共7米长，4米宽，与客厅相连有一南阳台，与客 厅同宽，长1.5米。餐厅的北面是卫生间，卫生间与厨房相对， 中间由1米宽，3米长的过道隔开；卫生间门对着过道，南墙与 厨房的南墙在一条直线上；卫生间为长方形，南墙长3米，另一 边长2米。卫生间的北面是次卧，同宽，门朝着过道，次卧长4 米。过道的北端是书房门，书房南北长4米，书房有一个一米见 方的门厅，书房的西墙长4米，包括1米长的门厅长度，西墙把 书房和次卧分隔开。门厅东墙北端90角折向东，长2米，把书房 和厨房北阳台分隔开。
练习
2.2.18 R.FUNC. 018支持XRN堆叠 …… 3.Process 处理 当unit down时，处理端口删除消息，把down掉的unit端口从镜像组中 删除，由此可能有相应的镜像组状态的改变。 当收到unit up消息时，本unit向其它unit发送端口镜像同步消息。此 消息包含本unit所配置的镜像组信息。
―可能”、“流畅”都是不 2.2.1 Performance Requirements 性能需求 清晰的，不同人理解不一 1. Performance Requirements1 性能需求1 样。 通话语音要求流畅。 不清晰一般也不可验证。
25
SRS大纲
简介
目的 范围
总体设计约束
标准符合性 硬件约束 技术限制