技术文档写作技巧

如何写一篇好的技术文档
最近在公司内部审查（Review） 一篇详细设计文档时，对于文档作者所写的文档 觉得很多地方需要改进。对于其中所存在的值得提高的地方，我想不是我们中国 软件行业的个别问题，相反，存在一定的普遍性。以下我列出了几个值得提高的 地方。
1）        文档的格式上存在不一致性的问题。格式有时是这样，有时是那样。一篇好 的文档我想不光是内容写得好，其格式是很重要的一部分。试想，如果我们拿到 了一篇格 式上写得乱七八糟的文档，这一第一印象会影响我们的阅读心情吗？ 好的文档应当是从头到尾保持格式的一致性， 这不仅仅是一种美，更是专业性的 一种表现。
2）        写文档的作者不能很好的站在读者的角度去思考。要写出一篇好的支持文档， 作者应当站在读者的角度上去写。这简单的一句话，要操作起来，将其做好，还 真不是一件容易的事。在写文档时，如果不站在读者的角度去思考，很容易写 出一篇“自己一看觉得活活楚楚，别人一看却糊里糊涂”的文档。
3）        文档求长不求 精。一说到写文档，我不知是否有人将“文档应当长”当作是
文档的必要届性。对于这一点，我想正确的态度是：求精不求长。一篇好的文档, 应当写得简练易懂。        写文档的目的是什么？是为了让别人明白我们所要说明的
问题，要说明问题，并不需要一定将其写得长。一篇精炼的文档也意味着效率， 即读者花很少的时间就明白 我们想要表达的问题是什么。当然，从作者的角度 来看，要写一篇精炼的文档，那得花更多的时间去斟酌。
4）        图太少。有图不是一篇好文档的必要条件，但在不少情况下，用一幅图能很
好的表达我们的思想，不是有那么一句话吗“好图胜过千言万语”， 适当的采用 一些图，一方面能为文档增色，另一方面也能更好的向读者传达我们的意图。
好了，值得提高的点也提出来了，如何去做好呢？我想下面是我所能想到的一些 方法，在此，将与上面的提高点一一对应进行阐述。
1）        对于格式问题，找一篇自己觉得格式不错的文档进行模仿，并将其做成一个 棋板，每次写作时以这一模板为基础。
2）        写完以后，假设自己是读者多次阅读自己的文档。
　这一点要做好还是很难的， 因为，我们很难完全站在读者的角度去读自己写的文档， 我们不知道自己所知的 哪些东西是读者所不知的，即很难界定与读者知识不对称的分界点。为了提高 这一点，我想我们写文档时，应当多问自己一些问题，比如，读者具有与我一样 的知识和经验 吗？如果没有，我应当写哪些以弥补这种信息的不对称性呢？我
写的这篇文档是基于一定的假设吗？如果是， 是否应当将这一假设在文档中交代 活楚呢？我所写的内 容是否都在支持文档的主题呢？是否存在正交问题（即答 非所问的问题）？等等。
3）        在文档写完后多问一问自己，这篇文档还能写得更简单吗？是否可以将一些
文字省去并用一幅图取而代之以达到使其简练的目的呢？不防时刻对自己说，        简
单也是一种美！
4） 学习（并精通）一些行业所需的图形语言和工具，并加以运用。比如，我们 软件行业的UMLM是很好的一种表达语言，且随着UML勺发展，其表达能力更加 的强 大。目前，业内有很我UML勺工具，找一个不错的就行了，比如 Visual Paradigm的UMLX具就不错，工具其实只是一种工具，关键是掌握UML只有我 们很好的掌握一种图形语言，我们才有可能随时加以运用，从而为我们        的技术 文档服务。当然，像Microsoft的Viso也是不错的绘图工具，这要看我们想表 达的是什么，从而加以灵活运用各种工具。
至 此就好了吗？不，还有很重要的一点是：我们需要在思想上做一些改变，这 种改变是什么呢？那就是：写出一篇好的技术文档是一个专业软件工程师的必要 素养！我 们必须抛弃那种软件工程帅只要能写出漂亮的代码就行了的思想，而 是要将“写好每一篇技术文档是专业软件工程师的必要素养”这一句话深入到 我们的骨髓当中 去，只有这样，我们所写的技术文档才会越来越好、才会越来 越专业。
“李云” 博客   /831344/168352

靠谱