51Testing软件测试论坛

标题: 分享我的用户手册编写规范 [打印本页]

作者: mallybel 时间: 2018-11-9 11:23
标题: 分享我的用户手册编写规范
用户手册编写规范

GB/T12504-1990标准中对计算机软件质量保证计划进行了规范，要求用户文档(例如手册、指南等)必须指明成功运行该软件所需要的数据、控制命令以及运行条件等；必须指明所有的出错信息、含义及其修改方法，还必须描述将用户发现的错误或问题通知项目承办单位(或软件开发单位)或项目委托单位的方法。
写手册要以上诉规范为准则，根据项目情况适当变通。
写手册的时有写完要自己多读几遍，假定用户手册受众就在对面听你讲的场景。能用简洁语言表达清楚的就不要太啰嗦，尽量不要太白话文。用户手册能够教会用户使用每个功能即可，具体实现逻辑、算法相关可不必讲太清楚，逻辑算法是用例里写给测试看的。

手册编写注意以下几点：

1.首行缩进2字、字体、字样、标题、图片编号规则要统一。目前一级标题宋体二号，二级标题宋体三号，三级标题宋体小三，正文是宋体五号，图片下方编号及名称是宋体小五。

2.总体章节功能架构要按系统从上到下从左到右的习惯排序。

3.章节编号都应该是自增长的不要自己写死。

4.最好不要出现节号是四组数字的显得文章太碎。

5.同级的要点标记如果用数字标记（1.  2.  3.）其他章节下的也都用数字编号。如果用项目符号就都用项目符号，不要混着用，上下级关系的可以区分，但全文风格要统一。

6.手册截图最好不要有菜单列。因为才单列的顺序不一定固定就是这种，而且有的模块可能不给个别用户用。
（注意：这是为了减少手册维护工作的，但是如果考虑以后要申请软著等最好截全图。因为最近软著申请审核严格了要求全图）
7.截图时要做模仿真实数据，不要乱七八糟的数据，样板数据最少3条，不会显得空。如果一条数据高度太高，可以考虑图片截取的美观性截2条样板数据

8.截图不要截logo，因为每个用户可能定制不同的logo，让用户看到别人的logo不好。

9.图尽量少截，如果语言描述的已经很清楚不需要每个功能都配图。

10.文中的“如图XXXX”可以不带就不带，因为考虑到以后修改手册可能插入、删除图片，图片编号顺序需要修改的，写多了改的时候会有遗漏。

11.图片下方图片编号及名称字体大小全文要统一，格式是编号+一个空格+名称；要居中。

12.图片编号按照图1、图2 方式命名，每个小结重新编号。
（btw.这点也是为了之后维护手册时可能会插入章节，才要求不要按章节编号来命名图片编号修改起来麻烦）

13.模块、按钮标记方式要统一，如果用【】括起来，每个模块都要括起来。

14.没有实现的功能不要写。

--------------------------------
补充1：移动端图片要截整屏不要截半屏，如果数据少可以造写数据，如果实在是页面设计的就很空也没办法。也要截整屏；

补充2：移动端图片大小要统一控制在相同的刻度范围，例如，手机端第一张图截的是横6~34，纵向1~31之间就要一直保持在设个范围，不要相差太多。

补充3：移动端图片要加阴影效果。图片工具-图片效果-阴影-外部-居中偏移。给用户感觉有手机/平板的厚重感

补充4：移动端因为有安卓端和ios端，大家在写手册时要说明是以什么为例，如手机以IOS端，平板以安卓为例。最好截图都用同一款设备。不要一个手册里出现两种操作系统的截图。

手册常见问题：

1.语法问题

非正常断句：一句话非得断成两句，前不成句，后不成句。例如松桃报名管理模块手册中有句“点击【设置】按钮，可对报名的开始时间，重新设置”。

错误使用关联词：一句话明明没有转折关系，非的放个“但”字在里面。例如报名系统手册中有句“同一学校、学期只可增加一次报名时间，但可以修改报名时间；”  为什么要用个但字呢？

还有其他词语使用不当，例如只有....才......

两个谓语：手册中经常看到有人喜欢用“可进行新增/修改/删除....”  ，“进行”是多余的。

2.拷贝其他系统类似的功能手册后没有修改。这个现象非常常见，很严重。

3.首行未缩进，句尾没有标点符号。

4.不要罗列系统中的查询条件。例如某列表查询条件有n个，手册中就写了n个。这种不利于以后的手册维护，条件一旦变更就需要修改手册。建议改成可根据系统提供的查询条件筛选列表记录。

5.多个应用分开写手册，单独使用某个功能时，使用场景没有交代清楚，缺少引导用户怎么用这一环节。

6.偶然发现手册编写思路不清晰，逻辑自相矛盾。例如，“学生初始状态未待报名，点击【报名】，报名成功后，学生状态变成待缴费，点击【缴费】，选择设置的缴费类型，缴费成功后，即报名成功。”，到底先有报名成功还是先有缴费成功？

7.偶然也会发现功能描述错误，甚至是与实际实现结果相反的描述。例如手册中说“共享审核中和已共享的资源不能编辑。”，而实际上是可以编辑的。

作者: 海海豚 时间: 2018-11-9 11:40
谢谢分享~

作者: yasuobeijing 时间: 2018-11-14 20:36

欢迎光临 51Testing软件测试论坛 (http://bbs.51testing.com/)