编写帮助文档经验总结

 

自从编程脱离了刀耕火种的时代以来，文档就是程序的重要组成部分。而且各种名目的文档无所不有。对于写代码出身的人来说，往往相当不重视文档的编写。但是不幸的是，作为软件支持的重要组成部分，很多时候，文档却能影响软件产品的成败。

 

笔者一个月写帮助文档的经历实在是感触颇多，总结出来希望能给大家一些帮助。入门水平，特为没有写过文档而又计划写文档而准备。

 

如无特别说明，下面的文档特指CHM类型的帮助文档。不是Java的那种可以生成的API帮助文档，而是指用户手册。与Sandcastle等不是一回事。

 

一．人员配备

做事第一步，就是要选人。无数的书已经介绍过选正确的人的重要性，这里就不赘述了。大约需要三种实际做事儿的人。

1.         文档编写者：实际编写文档内容的人。如果资金和时间都比较充足可以由专门的人员来做。能做出高品质的文档。但是这种情况在广大的中小项目中比较少。多种情况下，编写文档的人会是程序的设计或开发大员。他们熟悉项目，省去了培训的成本，但是工作性质的不同决定了他们一开始写出的文档品质相当的不高。对项目的过度熟悉让他们潜意识地觉得文档没有什么内容好写。

2.         文档审查：负责文档的内容正确性，用语准确、简洁。说白了就是英语文档的语法、词汇检查。同时也许要负责文档基本样式的定制和进度的安排。不要以为英文文档才需要，就是中文文档，不同人写出来的风格也不一样。但是文档是要有统一的风格的，所以一定有人专门的人负责这个广义的风格。这个人最好有一定的计算机使用功底，不是随便一个英语好的就OK的。

3.         技术支持：一般是兼职，要做的事实在不多，但是这部分的工作也是很重要的。主要包括如下的几个方面：

(1)       负责HTML文档的模版。

(2)       CSS的编写和维护：没有一个共享的CSS维护页面的样式可是很不专业的表现。

(3)       CHM项目的维护：要有完整的目录和索引。

(4)       程序与CHM的整合：当用户在程序的一个地方按F1时，要能打开CHM的相关主题页。

 

二．工具选择

1.         HTML编辑工具：就是用什么软件写文档的问题。一直都是做.NET开发，所以选择HTML编辑也大都在MS阵营里选。主要有以下几种HTML编辑器。

(1)       Dreamweaver：做WEB开发的老大级产品。但是用来手写HTML确实有点杀鸡用牛刀的嫌疑。

(2)       Visual Studio：如果用VS开发程序，那么写文档直接用VS打开HTML就可以了。不过界面不太友好。

(3)       Expression Web：Expression套装的重要组件，由FrontPage发展而来。良好的代码自动完成功能。Design界面等和VS的实在是很像，感觉很可能用了同一个内核。一个缺点就是不会监视文件的外部更改。这个东西是要买的，不买的话只有一个多月的试用期，如果不想花钱，而文档计划又要在一个月之内完成。用这个是很合适的。

(4)       各种Office：比如Microsoft Office、Open Office等都可以用来编写HTML。也是最差之选。有了模版之后，用记事本也比这个强。生成的HTML有大量垃圾代码，没有CSS，多人编写时不便于merge。不到万不得已绝对不要用这个东西写HTML文档。用这个东西唯一好处就是方便领导Review。加批注比较方便。而Open Office的优点就是免费。

2.         文件管理平台：文档文件多了，写文档的人和审阅文件的人一起工作难免会有同步文件的问题。为了解决这个问题，可以用CVS，Source Safe，Perforce之类的源文件管理软件帮助维护文档文件。文件多，人也多的时候，这一点非常重要。

 

三．注意事项 

1.       由于是HTML文档，其中的Hyperlink是依赖于文件名的（程序员都知道，不过审阅文档的可不一定，一高兴把文件名改了不是玩的）。所以轻易不要改文件名。有哪些文档，都叫什么，最好写写之前确定下来。

2.       如果使用HTML Help Workshop生成CHM，文件名不要有’&’等字符。不然会让链接失效。（发现有些MS软件的CHM文档是用GUID当文件名，感觉很不好维护，不知这个HTML是不是从别的文件生成的。）

3.       每次开始写一种类型文档之前一定要有一个专门的会议确定要写什么，怎么写，详细到什么程序，以及文档的措辞，图片的选取等重要问题。如果时间充足，很有必要写一个文档的文档来进行规范化。不要因为所谓的时间紧为由，三言两语就打发人去开始写文档，一个新生写的文档一定不是你想要的文档。结果就是返工。而且即使都是老手，写得都对，但是一人一个写法，放一起还是不对。

4.       确定版权信息。一般页脚都会有版权声明。这个要事先确定，第一次就写正确。

5.       如果文件比较长，需要添加一定量的书签（锚点），以方便在索引和Hyperlink中精确定位。

 

 

从内容来看，广义上的帮助文档的大致可以分成两大部分。一部分介绍某个界面、控件等的作用；另一部分是介绍要完成特定操作时，需要在哪儿操作、如何操作。可以说是功能与界面的双向映射。只有当文档包含了这两个方面的内容的时候，文档才能够说是完整的。

我们身边有太多的资源可以利用，充分利用现有资源，就能更高效，更高质量地完成工作。而学习使用这些资源所付出的代价，绝对是值得的。

 

上面皮毛性的总结都是源于个人最近一段时间编写文档的经历。不正确的地方还请大家指正。

最后更新于2009年1月6日，更新部分由蓝色标出。