首  页 综合布线 计算机网络 安全防范系统 一卡通系统 楼宇自控 新闻中心 九五简介 联系我们
 
 
新闻中心
技术文章
常见故障
企业动态
 
新闻中心 当前位置:新闻中心 << 技术文章 
[经验]如何写规范的网络工程技术文档
 
 
时间:2017/5/28 作者: 来源:合肥楼宇自控、合肥安全防范、合肥一卡通 浏览次数:5004 文字大小:【】【】【
 
写网络工程技术文档毫无疑问是有一套具体的规范的,能写出一篇漂亮的技术文档也是一个网络工程师应具备的能力之一。SPOTO的耿叔为了学生更好的掌握这一项必备的技能,特意罗列出这些规范。
     

文档分类:

解决方案类文档(面向内部、面向客户)

工程实施类文档(面向交付)

技术研发类文档(面向内部、知识分享、面向客户培训)

知识沉淀类文档(面向内容)

产品展示类文档(面向客户、面向网络)

文档编写思路:

明确目的

明确文档编写的目的,将直接影响整个文档撰写过程以及交付的成果,因此,务必要摸清楚交付目的:

例如:


1. 交付一份测试手册,关于S5750设备的Ipv6自动6to4隧道的功能,用于指导一线工程师工作

手册的目的是:指导一线工程师工作,那么这份文档,就要站在一线的角度去写,理解一线需要什么,或者一线的工作习惯等等。

2. 交付一份网络培训PPT,用于在项目实施后对客户进行培训


PPT的目的是:对客户进行项目实施后的培训,那么文档就要积极呈现服务的价值,以及公司的解决方案价值。同时帮助客户认识自己的网络,以及学习如何维护网络。

明确需求

这里的需求,并非简单意义上的概括,例如:“写一个项目实施报告,把这个项目的实施过程写一下”这个需求就太笼统了。

一个科学的需求,应该具备“SMART”原则,例如:

“写一份项目割接方案,详细描述网络现状、网络割接后的模型、割接步骤以及回退方案、IP及VLAN的割接前后规划、各方的职责、工时及进度表等等,下周二之前提交”

另一点要注意的是,一定要“找对人”确认需求,例如一份文档,如果使用对象是客户,但是交付对象是主管,那么这里需求应该和谁去确认呢?要注意的一点是,如果需求不明确,很可能产生无用功,浪费人力物力及时间。

明确对象

关注的对象应该有:文档的交付对象(提交给谁)、文档的使用人(谁用)明确对象,有助于找准准心。对象的明确,能够使得文档呈现更加的准确。

例如提交一份《故障处理报告》给内部,那么自然是实事求是,无论是产品或是环境问题可尽数呈现,但是如若是同一个内容,提交给客户,那么就要考虑下呈现的方式了,是否需要规避对品牌或者产品不利的因素等。再如,如若提交《实施手册》给内部工程师,那么可加强文档的专业度和针对性,如若提交给集成商,则需考虑集成商的技术水平,可适当加强文档的易用性和通俗性。

搜集信息

搜集文档所需的信息:例如撰写技术文档时,可能需要用到的设备参数、图片素材、网络环境素材等等。建议在日常工作或学习过程中,建立自己的KM,也即“知识管理”体系,将自己的所有“知识”,例如工作的积累、学习的材料,显性(看的见摸得着的)以及隐形(逻辑的如方法或技巧)保持阶段性整理和沉淀的习惯,例如笔者的个人电脑,建立知识管理目录:

小结:

大纲的编写是文档成型非常关键的第一步,明确了大纲,文档的总体架构就出来了。同时,把握好文档大纲,能够使得文档与需求的匹配度更高、文档的返修率降低等。
在文档撰写初期,强烈建议先编写大纲,并且与文档干系人,尤其是使用人确认大纲信息。

在完成大纲的基础上,填充文档的主题内容,这一步是工作量最大、最耗时的环节却也是最重要的环节。一个好的文档,给人的感觉是专业、规范、工整、简明扼要、可读性高、使用方便、维护方便等。
要编写好一份文档,除了上述说的种种,下面谈的云云,关键还在于个人对于所呈现的知识的理解程度、个人知识储备情况以及非常重要的一点,呈现技能。

在组织内部,文档和知识有一个统一化的管理,部分文档的发布有一套审核流程。通过了审核,基本就是一篇合格的技术文档了。


 


 
  加入收藏     打印此页     关闭窗口     返回顶部
 
 
 
版权所有:安徽九五网络科技有限公司http://www.ah95web.cn 皖ICP备06006112  
地址:合肥市蜀山区安粮国贸(金寨南路与东流路交口)1910室 电话:0551-65397195 65329185 13365699995 传真:0551-65318918
合肥网络工程,由九五网络网站建设中心推出,业务包括合肥网络工程,合肥综合布线,合肥局域网组建,合肥网络布线
.