怎么才能写好技术文档
2006-09-23 19:28
369 查看
有很多人都觉得我文档写的好。这不是一两个人说了。
我记得大概是在创业工作的时候,从写业绩点文档开始的。那时候,我自己给
做了一套模板。每次都按照这个格式写。每次都能得到领导的好评。既把自己
的工作都写进去了,还弄了个好名声。
在东信工作的时候,我就是软件组总体设计,专门写设计文档。写的还算好。
每个人都觉得写的还算好。
有朋友说让我介绍介绍经验。那我就在这里说说。其实,世上无难事,是怕
有心人啊。要做好一件事情,只要真心对待总能做好的,下面是关于写文档
的一点心得。写出来,以供探讨。本文主要讨论科技说明文档。不是写文章。
写好文档,注意点有:
一、思路清晰、章节分布合理
分章节、逐层深入地描述问题。这是写科技文档的要旨。看看MSDN和各家
软件公司的产品文档就可以知道,无一不是如此。
二、不用口语
科技说明文档,不用口语。不能出现“你们”、“我们”、“好啊”、
“咋样啊”、“应该”。。。。。。这些都不能出现。比如,“应该”应
写成“应”、“需”等书面用语。一些讨论稿可以适量使用口语。
文档代表公司和技术要点,不是体现个人魅力的地方。一个公司不能使用
五花八门风格的文档。口语的使用,更是会雪上加霜。
三、形成固定风格
科技文档不要求风格各异,但求达意简约。这个和写文章的方法是格格不入。
可以针对每类事务,形成固定的模板。所谓有章可循。要把它形成组织积累。
而不是个人行为。这样能形成整体风格。
四、站在读者的角度写
主要涉及到难度、叙述方式等。文档叙述的难易程度要和读者匹配。否则,
难了看不懂。太简单了,也没有意思。这些都没有起到效果。
五、解决问题是核心
任何文档写出来都是要解决问题,那就是帮助读者熟悉知识点。任何的形式、
风格、注意点都是表面的东西。解决问题是关键。
一个写的再好的文档,不能姐姐问题,都是白搭。
六、注意积累
积水成渊、积善成德。任何事情都不是与生俱来的。小孩子出生后,如果马上
就放到野兽的巢穴,也照样说不了话。写好文档也是如此。只有多写,认真写
才能写好。
我记得大概是在创业工作的时候,从写业绩点文档开始的。那时候,我自己给
做了一套模板。每次都按照这个格式写。每次都能得到领导的好评。既把自己
的工作都写进去了,还弄了个好名声。
在东信工作的时候,我就是软件组总体设计,专门写设计文档。写的还算好。
每个人都觉得写的还算好。
有朋友说让我介绍介绍经验。那我就在这里说说。其实,世上无难事,是怕
有心人啊。要做好一件事情,只要真心对待总能做好的,下面是关于写文档
的一点心得。写出来,以供探讨。本文主要讨论科技说明文档。不是写文章。
写好文档,注意点有:
一、思路清晰、章节分布合理
分章节、逐层深入地描述问题。这是写科技文档的要旨。看看MSDN和各家
软件公司的产品文档就可以知道,无一不是如此。
二、不用口语
科技说明文档,不用口语。不能出现“你们”、“我们”、“好啊”、
“咋样啊”、“应该”。。。。。。这些都不能出现。比如,“应该”应
写成“应”、“需”等书面用语。一些讨论稿可以适量使用口语。
文档代表公司和技术要点,不是体现个人魅力的地方。一个公司不能使用
五花八门风格的文档。口语的使用,更是会雪上加霜。
三、形成固定风格
科技文档不要求风格各异,但求达意简约。这个和写文章的方法是格格不入。
可以针对每类事务,形成固定的模板。所谓有章可循。要把它形成组织积累。
而不是个人行为。这样能形成整体风格。
四、站在读者的角度写
主要涉及到难度、叙述方式等。文档叙述的难易程度要和读者匹配。否则,
难了看不懂。太简单了,也没有意思。这些都没有起到效果。
五、解决问题是核心
任何文档写出来都是要解决问题,那就是帮助读者熟悉知识点。任何的形式、
风格、注意点都是表面的东西。解决问题是关键。
一个写的再好的文档,不能姐姐问题,都是白搭。
六、注意积累
积水成渊、积善成德。任何事情都不是与生俱来的。小孩子出生后,如果马上
就放到野兽的巢穴,也照样说不了话。写好文档也是如此。只有多写,认真写
才能写好。
相关文章推荐
- 大家帮忙看看如果面对这个升级文档该怎么处理,或者怎样才能处理得快一些(问在tianvcms改版前)
- 怎么才能向技术大牛提切中要点的问题?本文教你如何高质量提问
- 怎么才能把ppt转换成word文档
- 怎么才能实现真正的ArcGIS版本压缩(Compress) - ArcGIS技术研究
- 技术文档怎么写呢?
- 数据集处理技术文档_DataReader(DataAdapter)转换到DataSet的.NET技术(介绍一个已经写好的实用类)
- 软件开发,怎么才能做好呢?(二)----设计文档
- 怎么才能写好一篇文章
- mac上的pdf编辑器怎么才能直接修改PDF文档上的字体大小
- word2010打开文档提示错误, 必须解除锁定才能打开, 要怎么设置才能去除这个?
- 【人工智能】IBM 林咏华:AI 技术基础薄弱的企业,应该怎么做才能享受 AI红利?
- 不知道怎么才能下载文档,积分跟资源分是一个么
- 用freemarker写.ftl页面时,怎么才能调用其他包中写好的系统时间(也就是在页面上显示系统时间)
- 怎么才能写好测试用例
- 如何写好技术文档
- 怎么写好文档
- 怎样写好技术文档
- 文档损坏怎么才能恢复
- 菜鸟程序员怎么才能提高自己的技术--(献给自己共勉)
- webservice的发布技术不同,客户端调用程序也不一样,从发布的wsdl文档,怎么判断webservice是哪种方式发布的?