谈谈技术文档的编写

博客园里讨论编程的文章很多，却没有见过谁发表过文档撰写方面的，或者有，是有我不知道呢？但无可否认的是，涉及到到文档方面的极为罕见。这是否与程序员对文档的编写不够重视有关呢。

作为一名程序员，我也曾经犯这样的错误，对于文档的编写不够重视。但是长期地和客户接触中，发现文档的撰写极为重要，出色文档绝对可以为你的软件锦上添花，同时，可以减少花在客户身上技术支持的时间。现在，我就谈谈写文档的一些心得。一份文档，应该是由以下几部份组成

文档的组成

1、软件的简介。这部份内容应该把软件的特点给描述清楚，让用户知道你的软件都有些什么功能、用途。对他们的工作或者生活有些什么帮助。这部份内容，应该是简洁明了，并且描述清楚的。让用户能够在一分钟之内，就能够作出判断，这个软件是不是他们想要的。最好能配上软件的截图，让用户对你的软件有个直观的认识。

2、使用授权。这是一个必不可少的部份，你必须清楚的认识，你以自己所写的软件是拥有版权的，授权哪些人，怎么授权是你权利。必须要告诉用户，他们在使用你的软件有些什么限制。一般来说，最好使用常用的协议，因为我估计，没有哪个用户愿意花太多的时间来仔细阅读你的授权协义。

3、快速入门。在这部份内容里，你应该教会用户使用你的软件。时间最好限制在三分钟之内。否则用户很容易会放弃。这部份内容的目的是让用户进一步了解你的软件，吸引用户去积极使用。所以，这部份内容要挑最重要，而又最简单，最能体现你软件特色的功能。

4、参考。这份内容应该是越详细越好。把你的软件、功能描述得面面俱到。这部份内容是让用户全面掌握软件的使用。

5、常见问题。在这部份内容里，应该罗列出用户最常到的一些问题。对于用户碰到的问题，能够迅速找到解决的答案。

6、HOW TO。这部份内容应该逻列一些常见的任务，然后一步步地教用户怎么去使用你的软件。把这部份内容称为 STEP BY STEP 也可以。这部份内容，一部是放在快速入门那里部份里。

以上几部份就是常见的文档组成。接着来谈谈文档的编写。一份好的文档，用户一眼看上去，要有一种赏心悦目的感觉。

文档的编写

1、文档要有索引，也就是目录。这个非常重要，因为它能迅速帮助用户定位到他所感兴趣的内空。

2、排版要美观。从我个人的经验来说，具体就是大标题要居中，多个的小标题要有序号。段与段之间的间隔要适中。不能都挤在一块，否则会影响阅读。

3、字体大小要清晰易看。简单点说，就是喵上一眼，就能了解到这个章节的结构。哪部份是标题，哪部份里摘要，哪部份是内容，哪部份是示例、哪些是关键字。这些都可能通过字体的大小，粗体，斜体，下划线这些来体现。另外，还有一个要注意正文内容的字体不能过小，否则长时间的阅读容易让眼睛疲劳，我一般都是选用5号字体。

4、字号要统一。就是说，标题，小标题，内容等等的字体，在每一个章节里，它的大小都是一致的。不能说，有些章节的标题是三号字体，有些章节的标题是四号字体。

大家如果对文档的编写感兴趣的话，可以到http://esql.codeplex.com 下载 ALinq Dynamic 来看看，它里面包含的一份中文文档，基本是按照上面所说的去编写的。关于 ALinq Dynamic 的介绍，你可以在这篇文章找到，《高仿Entity Framework？Linq to SQL也有春天！》 。

如果你觉得这篇文章对你有用，或者有所启发，请点一下支持。鼓励我继续写出更高质量的文章。