如何写一篇好的技术文档

最近在公司内部审查（Review）一篇详细设计文档时，对于文档作者所写的文档觉得很多地方需要改进。对于其中所存在的值得提高的地方，我想不是我们中国软件行业的个别问题，相反，存在一定的普遍性。以下我列出了几个值得提高的地方。

1）文档的格式上存在不一致性的问题。格式有时是这样，有时是那样。一篇好的文档我想不光是内容写得好，其格式是很重要的一部分。试想，如果我们拿到了一篇格式上写得乱七八糟的文档，这一第一印象会影响我们的阅读心情吗？好的文档应当是从头到尾保持格式的一致性，这不仅仅是一种美，更是专业性的一种表现。

2）写文档的作者不能很好的站在读者的角度去思考。要写出一篇好的支持文档，作者应当站在读者的角度上去写。这简单的一句话，要操作起来，将其做好，还真不是一件容易的事。在写文档时，如果不站在读者的角度去思考，很容易写出一篇“自己一看觉得清清楚楚，别人一看却糊里糊涂”的文档。

3）文档求长不求精。一说到写文档，我不知是否有人将“文档应当长”当作是文档的必要属性。对于这一点，我想正确的态度是：求精不求长。一篇好的文档，应当写得简练易懂。写文档的目的是什么？是为了让别人明白我们所要说明的问题，要说明问题，并不需要一定将其写得长。一篇精炼的文档也意味着效率，即读者花很少的时间就明白我们想要表达的问题是什么。当然，从作者的角度来看，要写一篇精炼的文档，那得花更多的时间去斟酌。

4）图太少。有图不是一篇好文档的必要条件，但在不少情况下，用一幅图能很好的表达我们的思想，不是有那么一句话吗“好图胜过千言万语”，适当的采用一些图，一方面能为文档增色，另一方面也能更好的向读者传达我们的意图。

好了，值得提高的点也提出来了，如何去做好呢？我想下面是我所能想到的一些方法，在此，将与上面的提高点一一对应进行阐述。

1）对于格式问题，找一篇自己觉得格式不错的文档进行模仿，并将其做成一个模板，每次写作时以这一模板为基础。

2）写完以后，假设自己是读者多次阅读自己的文档。这一点要做好还是很难的，因为，我们很难完全站在读者的角度去读自己写的文档，我们不知道自己所知的哪些东西是读者所不知的，即很难界定与读者知识不对称的分界点。为了提高这一点，我想我们写文档时，应当多问自己一些问题，比如，读者具有与我一样的知识和经验吗？如果没有，我应当写哪些以弥补这种信息的不对称性呢？我写的这篇文档是基于一定的假设吗？如果是，是否应当将这一假设在文档中交代清楚呢？我所写的内容是否都在支持文档的主题呢？是否存在正交问题（即答非所问的问题）？等等。

3）在文档写完后多问一问自己，这篇文档还能写得更简单吗？是否可以将一些文字省去并用一幅图取而代之以达到使其简练的目的呢？不防时刻对自己说，简单也是一种美！

4）学习（并精通）一些行业所需的图形语言和工具，并加以运用。比如，我们软件行业的UML就是很好的一种表达语言，且随着UML的发展，其表达能力更加的强大。目前，业内有很我UML的工具，找一个不错的就行了，比如Visual Paradigm的UML工具就不错，工具其实只是一种工具，关键是掌握UML。只有我们很好的掌握一种图形语言，我们才有可能随时加以运用，从而为我们的技术文档服务。当然，像Microsoft的Viso也是不错的绘图工具，这要看我们想表达的是什么，从而加以灵活运用各种工具。

至此就好了吗？不，还有很重要的一点是：我们需要在思想上做一些改变，这种改变是什么呢？那就是：写出一篇好的技术文档是一个专业软件工程师的必要素养！我们必须抛弃那种软件工程师只要能写出漂亮的代码就行了的思想，而是要将“写好每一篇技术文档是专业软件工程师的必要素养”这一句话深入到我们的骨髓当中去，只有这样，我们所写的技术文档才会越来越好、才会越来越专业。