网络工程技术文档编写规范.pdf

网络工程技术文档编写规范 by 红茶三杯
网络工程技术文档编写规范
版本
密级开放内部机密
类型讨论版测试版正式版

修订记录
修订日期修订人版本号审核人修订说明
2010-04-22 红茶三杯
2012-05-27 红茶三杯


1 前言
文档目的
为提高我司技术服务工程师工程文档编写能力、统一文档呈现界面、统一化文档管理、提高文档专业
性及可读性,特此下发此规范。
良好的文档呈现能力,能够:
更好的沉淀、传播知识
加快个人、组织的“知识管理”进程;提高知识沉淀质量
更好地体现工作价值及提升个人品牌形象,从而提升团队或公司的专业形象
提高工作效率
保障优先沟通
学习●沉淀●成长●分享 1
网络工程技术文档编写规范 by 红茶三杯
网络工程文档类型
我公司层面文档类型主要分为:
解决方案类文档(面向内部、面向客户)
工程实施类文档(面向交付)
技术研发类文档(面向内部、知识分享、面向客户培训)
知识沉淀类文档(面向内容)
产品展示类文档(面向客户、面向网络)
2 文档编写规范
文档编写思路


步骤分解
明确目的
明确文档编写的目的,将直接影响整个文档撰写过程以及交付的成果,因此,务必要摸清楚交付目的:
例如:
1. 交付一份测试手册,关于 S5750 设备的 Ipv6 自动 6to4 隧道的功能,用于指导一线工程师工作
手册的目的是:指导一线工程师工作,那么这份文档,就要站在一线的角度去写,理解一线需要什
学习●沉淀●成长●分享 2
网络工程技术文档编写规范 by 红茶三杯
么,或者一线的工作习惯等等。
2. 交付一份网络培训 PPT,用于在项目实施后对客户进行培训
PPT 的目的是对客户进行项目实施后的培训,那么文档就要积极呈现服务的价值,以及公司的解
决方案价值。同时帮助客户认识自己的网络,以及学习如何维护网络。
明确需求
这里的需求,并非简单意义上的概括,例如:“写一个项目实施报告,把这个项目的实施过程写一
下”这个需求就太笼统了。
一个科学的需求,应该具备“SMART”原则,例如:
“写一份项目割接方案,详细描述网络现状、网络割接后的模型、割接步骤以及回退方案、IP 及 VLAN
的割接前后规划、各方的职责、工时及进度表等等,下周二之前提交”
另一点要注意的是,一定要“找对人”确认需求,例如一份文档,如果使用对象是客户,但是交付对象
是主管,那么这里需求应该和谁去确认呢?要注意的一点是,如果需求不明确,很可能产生无用功,
浪费人力物力及时间。
明确对象
关注的对象应该有:文档的交付对象(提交给谁)、文档的使用人(谁用)明确对象,有助于找准
准心。对象的明确,能够使得文档呈现更加的准确。
例如提交一份《故障处理报告》给内部,那么自然是实事求是,无论是产品或是环境问题可尽数呈
现,但是如若是同一个内容,提交给客户,那么就要考虑下呈现的方式了,是否需要规避对品牌或者
产品不利的因素等。再如,如若提交《实施手册》给内部工程师,那么可加强文档的专业度和针对性,
如若提交给集成商,则需考虑集成商的技术水平,可适当加强文档的易用性和通俗性。
搜集信息
搜集文档所需的信息:例如撰写技术文档时,可能需要用到的设备参数、图片素材、网络环境素材
等等。建议在日常工作或学习过程中,建立自己的 KM,也即“知识管理”体系,将自己的所有“知识”,
例如工作的积累、学习的材料,显性(看的见摸得着的)以及隐形(逻辑的如方法或技巧)保持阶段
性整理和沉淀的习惯,例如笔者的个人电脑,建立知识管理目录:
学习●沉淀●成长●分享 3
网络工程技术文档编写规范 by 红茶三杯

如此一来信息的定位就会非常快速。关于知识管理的进一步内容,详见 bbs. 雏鹰部落论坛的
BOOTCAMP 板块中“知识管理”一帖。
编写大纲
大纲的编写是文档成型非常关键的第一步,明确了大纲,文档的总体架构就出来了。同时,把握好
文档大纲,能够使得文档与需求的匹配度更高、文档的返修率降低等。
在文档撰写初期,强烈建议先编写大纲,并且与文档干系人,尤其是使用人确认大纲信息。
例如,撰写一个《xx 网络割接方案》,大纲可参考如下:
方案背景
现网环境
改造后环境
割接过程(含回退方案、二三层信息规划)
配置规范