如何写出好的技术文档

如何写出一篇好的技术文档

最近在公司内部的文档评比中表现不佳，本人回顾参赛的文档发现有很多地方需要改进。以下我列出了几个普遍存在的问题，供大家参考，以提高文档质量。1）文档的格式

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

好格式举例：

a)标题：黑体，四号，加粗，居中；

b)摘要及关键词：宋体，小四；

c)一级标题：小四号，宋体，加粗；

d)二级标题：小四号，宋体；

e)正文内容：宋体，小四，不加粗，开头空两字；

f)行间距：1.5倍行距；

2）文档的选题

俗话说，“好的选题是成功的一半”。一篇技术文档的选题能够决定文档的价值和效用。好的选题可以规划文档的方向、研究角度和规模，来弥补贮备的不足。好的选题可以保证写作的顺利进行，提高研究深度。

那么，好的选题应该具备哪些因素？

a)能够解决现实中遇到的问题，或产生直接的经济效益；

b)有一定的技术深度，且对工作有帮助；

c)内容新颖，其他渠道无法轻易获取，且对未来的工作有帮助；

3） 文档的表达

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

以下列举几点注意事项：

a) 文档求精不求长

不少将“文档应当长”当作是文档的必要属性。但一篇好的文档，应当写得简练易懂。写文档的目的是什么？是为了让别人明白我们所要说明的问题，要说明问题，并不需要一定将其写得长。一篇精炼的文档也意味着效率，即读者花很少的时间就明白我们想要表达的问题是什么。当然，从作者的角度来看，要写一篇精炼的文档，那得花更多的时间去斟酌。 b) 能用表格表达，就不写文字；能用图片表达，就不列表格

有图不是一篇好文档的必要条件。但在不少情况下，一幅图更能很好的表达我们的思想，适当的采用一些图，一方面能为文档增色，另一方面也能更好的向读者传达我们的意图。一下几种方式，你更喜欢哪种？

数据 阶段 问题总数 研发反馈 44% IQC 反馈 12% 生产反馈 36% 市场反馈 8% 44%12%36%8%问题来源分类研发反馈IQC 反馈生产反馈市场反馈本月收集到的问题来源占比如下：研发反馈44%；IQC 反馈12%；生产反馈36%；市场反馈8%。反馈的问题主要来源于研发、生产。

c)上到文档，下到每段文字都有一个简明的摘要

站在读者角度考虑，要让读者在很短的时间内了解你要表达的意思。

光靠简洁还是不够的。在文档醒目的位置加入适当的摘要，往往令你“事半功倍”。

4）文档的检查

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