明确目的
明确文档编写的目的,将直接影响整个文档撰写过程以及交付的成果,因此,务必要摸清楚交付目的:
例如:
1. 交付一份测试手册,关于S5750设备的Ipv6自动6to4隧道的功能,用于指导一线工程师工作
手册的目的是:指导一线工程师工作,那么这份文档,就要站在一线的角度去写,理解一线需要什么,或者一线的工作习惯等等。
2. 交付一份网络培训PPT,用于在项目实施后对客户进行培训
PPT的目的是:对客户进行项目实施后的培训,那么文档就要积极呈现服务的价值,以及公司的解决方案价值。同时帮助客户认识自己的网络,以及学习如何维护网络。
明确需求
这里的需求,并非简单意义上的概括,例如:“写一个项目实施报告,把这个项目的实施过程写一下”这个需求就太笼统了。
一个科学的需求,应该具备“SMART”原则,例如:
“写一份项目割接方案,详细描述网络现状、网络割接后的模型、割接步骤以及回退方案、IP及VLAN的割接前后规划、各方的职责、工时及进度表等等,下周二之前提交”
另一点要注意的是,一定要“找对人”确认需求,例如一份文档,如果使用对象是客户,但是交付对象是主管,那么这里需求应该和谁去确认呢?要注意的一点是,如果需求不明确,很可能产生无用功,浪费人力物力及时间。
明确对象
关注的对象应该有:文档的交付对象(提交给谁)、文档的使用人(谁用)明确对象,有助于找准准心。对象的明确,能够使得文档呈现更加的准确。
例如提交一份《故障处理报告》给内部,那么自然是实事求是,无论是产品或是环境问题可尽数呈现,但是如若是同一个内容,提交给客户,那么就要考虑下呈现的方式了,是否需要规避对品牌或者产品不利的因素等。再如,如若提交《实施手册》给内部工程师,那么可加强文档的专业度和针对性,如若提交给集成商,则需考虑集成商的技术水平,可适当加强文档的易用性和通俗性。
搜集信息
搜集文档所需的信息:例如撰写技术文档时,可能需要用到的设备参数、图片素材、网络环境素材等等。建议在日常工作或学习过程中,建立自己的KM,也即“知识管理”体系,将自己的所有“知识”,例如工作的积累、学习的材料,显性(看的见摸得着的)以及隐形(逻辑的如方法或技巧)保持阶段性整理和沉淀的习惯,例如笔者的个人电脑,建立知识管理目录:
小结:
大纲的编写是文档成型非常关键的第一步,明确了大纲,文档的总体架构就出来了。同时,把握好文档大纲,能够使得文档与需求的匹配度更高、文档的返修率降低等。
在文档撰写初期,强烈建议先编写大纲,并且与文档干系人,尤其是使用人确认大纲信息。
在完成大纲的基础上,填充文档的主题内容,这一步是工作量最大、最耗时的环节却也是最重要的环节。一个好的文档,给人的感觉是专业、规范、工整、简明扼要、可读性高、使用方便、维护方便等。
要编写好一份文档,除了上述说的种种,下面谈的云云,关键还在于个人对于所呈现的知识的理解程度、个人知识储备情况以及非常重要的一点,呈现技能。
在组织内部,文档和知识有一个统一化的管理,部分文档的发布有一套审核流程。通过了审核,基本就是一篇合格的技术文档了。