原始链接:http://bbs.giltworld.com/dispbbs.asp?BoardID=46&ID=4795
如果你是一个新手,或者你的时间很紧张,你面临的主要工作是把一个技术文档写出来而不是高质量地完成文档,那么我这里先介绍一个快速写作的方法。如果你是熟手,那么可以跳过这段。
快速写作过程如果用一句话来说,就是从最简单的开始写。快速写作的大致过程如下:
步骤1 了解并确定用户需要的5个任务
步骤2 从这5个任务开始写,边学边写
步骤3 补充这5个任务的前提条件、后继要求以及相关任务,
步骤4 补充任务的目的,给这个任务加上标题
步骤5 根据前提条件、后继要求以及相关任务、补写其它任务,每个任务按照步骤2~4的方式去做
步骤6 补充需要的描述和参考
步骤7 重新组织你的文档的结构
步骤8 修改你的语言和文字
步骤9 写前言和概述
步骤10 安全事项、设置目录
(我这里提到的步骤,严格说,是伪步骤。关于步骤和伪步骤的概念我以后再说,这里记住,不要仿照我的这一段写你的技术文档)
下面我们详细讨论一下这个过程。一些基本技能我们就不讨论了,如如何在word中设置目录等,这些还是请参考其它方面的文档吧。
开始之前,你应该向你的团队要一个模板。在模板中写作,会让你省去很多的时间。模板的使用我们也不讨论了。
1. 了解用户需要的5个任务
这5个任务是可以任意的。当然,最好是常用的。
你可以从客户调研、客户座谈上了解,你也拜访用户专家,请他们提出来,甚至你可以任意想象。
这5个任务最好分布开,我的建议是你可以从这5个方面分别选择1个:
- 安装配置操作方面的,最好是配置方面。安装的过程基本上会想到,而且安装过程比较单一。如功能配置、接口设置、等等
- 安全操作方面的,如操作权限管理、防火墙设置等
- 性能提升和优化方面的,如性能统计、网络优化、自动控制响应阀值设置等
- 产出物统计或者帐务统计方面,如输出计量、流量统计、帐务报表
- 故障处理方面的,如告警设置、告警消除、障碍排除等等。
举例
我们就从一个网站的登录开始一个任务。
注意:
本节我们会一直使用这个例子。这个例子是针对网站使用的初学者的,一般专业网站的使用说明中,可能不需要这个任务。
2. 从一个任务开始写
当你确定了5个任务后,就从这5个任务开始写吧。
原则1-立刻就开始写。
你知道什么就写什么。如果你什么都不知道,那么就先学习这5个任务。你不甚至需要知道太多的东西,什么原理啊、写作规则啊,把它们先放到一边。你需要收集的和学习的信息也许仅仅是“做什么”和“怎么做”。
你可以根据文档写作的需要,去向SME(subject matter export主题专家)索取需要的信息。向SME索取信息时,一点忠告请参考,这样能给SME留下友善、聪明、好学的印象。
- 你在拜访前最好通过电话/邮件预约,并先声明准备好的问题。专家一般都好为人师,但要方式他也可能不知道。
- 拜访时,问一些聪明的问题,让SME能按照你的需要回答,也能显示你仅仅是一些关键点不清楚。最好不要问开放性的问题。如“这个设备是怎么运行的”“用户习惯怎么操作”之类的问题,很可能让你得不到需要的答案。
- 临时的拜访在10分钟内结束,因为SME很忙。
- 拜访后请快速回顾,确认和巩固你所学的知识。
原则2-直接从过程开始写。
举例
我们就可以根据上述原则写出一段网站登录的过程
1 在IE地址栏输入网址。
2 在用户登录区域框中输入用户名和密码。
3 回车或者单击<登录>。
4 显示登录成功。
5 如果错误,请核对帐号重新登录(发现少topic,忘记密码)
原则3-把过程改写为一步一步(step by step)的样式
这是很重要的一个过程。一般来说,每一步都应该有一个动作,这个动作的主语是人,而不是系统。每一个动作都会产生一个明确的结果,这个结果一般是设备或者其他人表现出来的。
举例
4 显示登录成功。
“显示”登录成功,是网站的回显信息,“显示”虽然是一个动词,但是它的主语是网页。因此这不是一个步骤。应该把它放到步骤3中。
5 如果错误,请核对帐号重新登录
核对虽然是一个动词,但不会产生明确的结果。因此这不是一步而是一个提示。
我们改写如下:
1 在IE地址栏输入网址。
2 在用户登录区域框中输入用户名和密码。
3 回车或者单击<登录>。
如果界面显示<登录成功>,你可以做其它的工作。
如果错误,请核对帐号重新登录。
原则4-简单补充一下你的每一步需要的信息。
简单一点,一般可能需要补充的信息是
- 明确的步骤的内容或者规则,如参数输入的原则,动作的持续时间、动作的幅度和范围等;
- 步骤中涉及的内部术语和概念,也可能是读者不熟悉的术语和概念。
- 图和表、以及图表的编号。
举例
1 在IE地址栏输入网址。
2 在用户登录区域框中输入用户名和密码。
步骤1中,对于特定的网站,我们应该直接告诉读者网址是什么。如果我们写的是giltworld论坛(假设,请谅解)的使用说明那么,我们就应该直接说明。
步骤2中的用户名和密码,我们也可以告诉读者他们的来历。
这样我们改写一下:
1 在IE地址栏输入网址bbs.giltworld.com
2 在用户登录区域框中输入用户名和密码。
用户名和密码是在您注册时输入的。如果您忘记了密码,请单击<忘记密码>
3 回车或者单击<登录>。
如果登录成功,你可以做其它的工作。
如果错误,请核对帐号重新登录。
原则5-在你写一个任务的操作说明的时候,请把你的手机关掉。
就是说,不要考虑太多的问题,一门心思指考虑你的这个任务怎么写。如果你发现有什么东西需要补充或者修改的时候,先放一放。比如你觉得应该写一些关于用户名和密码的规则,或者需要写怎么忘掉密码怎么办,那么就先做一个记号,然后放到一边,继续写你的过程。写完再说。
3. 补充这5个任务的前提条件、任务的结果、后继要求
前提条件是执行这个任务的上一个或者多个必备的任务。一般来说,如果有多个前提的任务,那么这些任务应该是并行的而不是串行的。如果是串行的,则说明最后一个任务即可。
例如,我们在登录一个网站前,必须安装电脑、安装操作系统、安装浏览器、注册用户名,然后才能进行登录。而由于注册用户名时肯定已经安装过浏览器了,那么,我们只要说明前提条件是注册用户即可。
任务的结果是你执行完一个任务应该获得的结果。这个结果应该是明晰可见或者可感觉的。标志着任务的结束。
例如,我们登录一个网站后,明确的结果应该是有在网站的某个位置显示出你登录的用户名。如果你需要说明任务的结果。那么你的结果不应该是登录成功,而是在某某位置显示出你的用户名。
后继要求是你结束这个任务后必须做的事情。例如,假如(由于某种原因)登录一个网站后,你不应该直接关闭网页而是应该先退出登录,然后再关闭网页,那么你的操作指导就应该在后继要求中说明。
举例
我们可以补充一下这个例子
前提条件
完成用户注册,获取有效的用户名和密码
过程
1 在IE地址栏输入网址bbs.giltworld.com
2 在用户登录区域框中输入用户名和密码。
用户名和密码是在您注册时输入的。如果您忘记了密码,请单击<忘记密码>
3 回车或者单击<登录>。
如果错误,请核对帐号重新登录。
结果
在网页的左上角,显示你的用户名
后继操作
退出时,请先单击注销再关闭网页。
说明:结果可以在最后一个步骤中描述。后继操作也可以用提示的方式说明。但无论什么方式,你应该在所有的任务描述中保持一致。
4. 补充任务的目的,以及相关信息,给这个任务加上标题
任务的目的,一般来说,是说明什么时候需要执行这个任务,或者执行这个任务会带来的成果。注意,目的不要重复标题,这样的话你还不如不写。
相关信息是指与这个任务相关的其它任务指导、概念说明以及其它需要详细说明的内容。相关信息将是你需要写的一段主题(章节),并且有标题。你现在可以仅仅写一下,以后等相关的描述完成后,你可以交叉链接等方式去修改。当然你也可以顺便把这些章节的的标题先列出来。
所谓相关,大致上包含了:
- 前提条件所涉及的任务
- 后继要求所涉及的任务
- 与本任务的题目的宾语相同或者相似的其它任务,比如增加用户,相同的就有删除用户、修改用户属性之类的。
- 本任务的反向操作
- 任务中的术语定义、或者对本任务的独立解释
- 任务中的某个步骤的详细参考信息,比如命令的说明,例子中的用户名密码的规则等。
标题应该是动宾结构的词组。
- 用词组不要用句子
- 要有动词,而且动词的隐含的主语是人
- 可以有状语,但如果有一定要短
举例:
登录XX网站
目的
需要浏览网站的详细内容并发表言论,你必须先登录网站。否则你只能按照游客的身份浏览网站的概况。
前提条件
完成用户注册,获取有效的用户名和密码。
过程
1 在IE地址栏输入网址bbs.giltworld.com
2 在用户登录区域框中输入用户名和密码。
用户名和密码是在您注册时输入的。如果您忘记了密码,请单击<忘记密码>
3 回车或者单击<登录>。
如果错误,请核对帐号重新登录。
结果
在网页的左上角,显示你的用户名
后继操作
退出时,请先单击注销再关闭网页。
参考信息
注册用户
用户名和密码规则
重新获取密码
登出网站
现在 ,你已经基本完成一段文档的写作了。
|