怎样写好技术文档

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

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

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

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

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

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

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

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

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

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

才能写好。

本文来自优快云博客，转载请标明出处：http://blog.youkuaiyun.com/truewaylee/archive/2006/09/23/1269379.aspx