如何提高文档编写能力

如何提高文档编写能力

分享一篇博文如何提高文档编写能力

在我身边的程序员中，无论是现在的同事还是过去的同事，普遍缺乏文档编写能力或能力严重不足，甚至有些编程能力很强的程序员也不能写出一篇可读性较强的设计说明书、产品手册等项目必备文档。其实，文档如何才能提高文档编写能力编写能力是成为优秀程序员和项目经理必须具备的能力，想要和更多人人进行交流只能通过你的文字来传达你的思想。该如何才能提高文档编写能力呢，可以采用了以下几种方法，只要坚持不懈的做下去，相信会有提高。

1、尝试编写个人简历和经历，用文字来认识自己是不错的方法。要想别人认识你，首先自己要认识自己。

2、养成良好的程序注释习惯，而且要用准确的语句描述注释的内容，从写注释的一句话开始锻炼文字表达能力。准确而简明的注释有助本人和他人阅读你的程序代码，语义不清或者错误的注释反而浪费了自己和他人的时间。

3、从编写较简单的文档（如：《XXX系统使用说明》）开始，锻炼文档编写的组织能力和文字表达能力

4、写博客。其实这也是我写博客的原因之一，想通过多写文章，用文字来准确的表达日常自己的所思所想来提高文档能力。还可以通过他人的评论和建议来改正不足之处。

5、阅读书籍和文章时除了学习里面的知识和技术外，还可以研究研究作者是怎么组织一篇文章和一本书籍的，通过怎样的一个内容结构来表达相关内容.

6、阅读一些写作技巧方面的文章提升技术文档编写能力也是显而易见的。

当然，要切实提高文档编写能力，需要勤于学习、勤于思考、勤于实践、长期积累，毕竟丰富知识和阅历才是写好文档的基础。

/////////////////////////////////////////////////////////////////////

如果提高自己的文档书写能力，像技术方案，概要设计，建议书，PPT. 对于一个问题，我见过牛人，写了几十页来讲解，我却挤了很久才挤出几个字来。

按照重要程度和先后顺序相结合回答如下：

1，考虑听的人看得人需求在哪里，什么样的东西是他们需要的，他们想要什么？比如你写一个方案给老板，就要从老板的角度考虑问题，是不是解决了他现在碰到的问题，你提出的解决方案考虑了执行了没有，执行的成本分析了没有，执行的过程中会碰到什么问题，执行中如何控制进度，执行后如何评估效果等等。

不管是技术方案，概要设计，建议书，PPT都要首先严肃认真的考虑这个问题。这一步特别的重要，当你站在自己的角度写出来的东西都是碰大运。

2，从这个思路开始，你要引入第一个工具，mindmap，如果你不熟悉，到维基百科查阅，软件可以到各种下载站找，有很多免费的mindmap工具

首先要站在受众的角度列出核心的需要，然后分解出子需要，如果可能再分解，然后针对每一个部分做出针对性描述和解决。

切记，受众已经知道的，千万不要写出来。

3，当你完成mindmap之后，要对行文的格式做一个初步了解

技术方案要重点探讨在原来基础上新增的部分，一定要针对新增的部分的先验

案例，不能让受众觉得有点悬不靠谱，可行性分析，解决方案，先验案例，费用，执行日程，监控等等，叙述要完整，有头有尾。

建议书重点在出发点、过程概要性的描述，结果和效果，引用数据和来源要明确，一切能够证明你的建议是对的东西都要明确罗列。

ppt一定要配合方案，只有ppt的方案都是空的。

概要设计最重要的是看你针对的是哪几种类型的受众，还是混合型的，要从设

计的核心开始讲起，逐步展开，在逻辑上要注意缜密、不要有明显的漏洞和遗缺。

4，最后是写了，一定要用好word里大纲和格式这两个功能，如果不清楚，google it。

在写的过程中我建议先根据前面几点所谈到的事项结合起来，先把提纲写好，

然后逐步添加内容，遇到不知道怎么添加的先放一下，把能写好的写完，然后

针对没有写的细节针对性的寻找解决的办法。

行文的风格要中性，严谨，形容词副词少用，多用定义明确的词汇和相当多的

专业词汇（根据受众而定），如果能用图表图片来表达的一定要优先使用。

千万不要从在某个地方停住，一定要从真个文档的角度从整体到细节的节奏来

完成。

5，最后是查漏补缺。

假设你讲完了，如果你是受众，你会提出什么问题？

把这些问题认真回答一下，放到对应的部分去。

//////////////////////////////////////////////////////////////////////////////////////////////////////

IBM文章：如何编写出好的用户需求文档

许多软件开发团队没有需求工程师；开发人员捕获、编写和管理所有的需求。这在资源效率方面是有意义的：开发人员可以在正式编码之前，在系统停机时间收集和编写需求。然而这一做法的缺点是，通常程序员没有在编写需求方面受过技术和工具的培训，结果他们总是费力和低效地工作，而且有时做出的需求规约不符合规范。

为了写出好的代码，开发人员必须知道很多事情：诸如控制结构和调用约定之类的基本概念；至少一门程序设计语言，包括它的语法和结构；操作系统基础；以及如何使用诸如编译器、调试器、集成环境这类的技术。好在他们能以所有这些知识为跳板写出好的需求来。通过应用许多与他们编写代码时相同的原则和概念，开发人员可以有效地担当起需求工程师的职责。

让我们看一些开发人员可以利用的编程概念。

遵循结构

所有的程序设计语言都有一种结构。这种结构指出程序的不同部分如何定义，彼此之间形成何种关系。Java程序由类来形成结构，COBOL程序有不同的“区段”，C程序有一个主程序以及多个子程序。

程序有一个特定的结构，需求也是如此。设想你把一个C程序的所有代码都塞到主程序里——它会变得不可读而且无法维护。与此相似，如果你的需求规约只是一张毫无规则的大列表，你也没办法使用它。不管你意识到没有，一组需求总有一个结构。获得需求中结构的最佳方法是把它们按不同类型来组织，而这些类型常常对应着不同的级别。

为理解不同类型之间的差别，我们来看看用于保险索赔处理的四条需求样例：

我们必须有能力处理积压下来的索赔单据。

系统必须能自动检查索赔表单以获得适用条款。

对索赔者，系统要根据其社会保险号码确定其是否是注册用户。

系统要支持处理多至100个并发的索赔请求。

你的直觉或许会告诉你其中每条需求都有一些不同的东西。第一条需求是级别很高的；它在表达业务需要的时候甚至没有提到系统本身。第二条需求表达了系统应该做什么，但仍在较高的级别上；它仍然太宽泛，不能直接翻译成代码。第三条是低级别的需求；它确实为软件必须完成的功能提供了足够的细节，使你能写成代码。第四条需求虽然非常详细，但并没有告诉你系统必须做什么；它只是规定了系统必须有多快。当你跟用户和其他涉众打交道时，这些需求是非常典型的。也许你已经看到为什么把它们放在一个大而无组织的表上会导致混乱。

为使需求更为可用，你可以把它们按范畴或类型分开，比如：

业务需要

特性

功能性软件需求

非功能性软件需求

这是IBM Rational Unified Process(RUP)中建议的类型。它们绝非唯一可能的类型，但它们表达了一种有用的方法。在你的项目的早期，就要决定用什么类型。这样，在你从涉众那里收集信息时，要确定他们描述的是何种需求类型，然后写成需求。

注意你可以用两种格式之一指定功能性软件需求：声明形式和用例形式。上述第三条需求是声明形式的；它是粗线条的，用了一个“要……”的句式。另一个形式是用例的，它也指定了系统应该做什么，级别足够低，能直接写成代码，不过它提供了更多的上下文，告诉用户和系统应该如何交互以执行一些有价值的东西。（关于用例的更多细节见下文。）在你着手收集项目需求之前，你应该确定哪一类功能型需求是你要用的，以后就不要改变。

用习惯保证质量