2007年8月10日星期五

怎么才能写好技术文档

有很多人都觉得我文档写的好。这不是一两个人说了。

我记得大概是在创业工作的时候,从写业绩点文档开始的。那时候,我自己给
做了一套模板。每次都按照这个格式写。每次都能得到领导的好评。既把自己
的工作都写进去了,还弄了个好名声。

在东信工作的时候,我就是软件组总体设计,专门写设计文档。写的还算好。
每个人都觉得写的还算好。

有朋友说让我介绍介绍经验。那我就在这里说说。其实,世上无难事,是怕
有心人啊。要做好一件事情,只要真心对待总能做好的,下面是关于写文档
的一点心得。写出来,以供探讨。本文主要讨论科技说明文档。不是写文章。

写好文档,注意点有:
一、思路清晰、章节分布合理
分章节、逐层深入地描述问题。这是写科技文档的要旨。看看MSDN和各家
软件公司的产品文档就可以知道,无一不是如此。

二、不用口语
科技说明文档,不用口语。不能出现“你们”、“我们”、“好啊”、
“咋样啊”、“应该”。。。。。。这些都不能出现。比如,“应该”应
写成“应”、“需”等书面用语。一些讨论稿可以适量使用口语。
文档代表公司和技术要点,不是体现个人魅力的地方。一个公司不能使用
五花八门风格的文档。口语的使用,更是会雪上加霜。

三、形成固定风格
科技文档不要求风格各异,但求达意简约。这个和写文章的方法是格格不入。
可以针对每类事务,形成固定的模板。所谓有章可循。要把它形成组织积累。
而不是个人行为。这样能形成整体风格。

四、站在读者的角度写
主要涉及到难度、叙述方式等。文档叙述的难易程度要和读者匹配。否则,
难了看不懂。太简单了,也没有意思。这些都没有起到效果。

五、解决问题是核心
任何文档写出来都是要解决问题,那就是帮助读者熟悉知识点。任何的形式、
风格、注意点都是表面的东西。解决问题是关键。
一个写的再好的文档,不能姐姐问题,都是白搭。

六、注意积累
积水成渊、积善成德。任何事情都不是与生俱来的。小孩子出生后,如果马上
就放到野兽的巢穴,也照样说不了话。写好文档也是如此。只有多写,认真写
才能写好。

没有评论: