10技巧创建软件开发文档

#7：使用新技术

即使所有工作都是正确的，文档编制的代价也是很高的。为了帮助开发更为有效的文档、节省开发费用将会不断推出各种新技术。我们可以将这些新技术看作降低文档编制过程的时间和费用的好机会。

作为项目小组的一部分，编制文档尤其困难。你的文档需要同其他小组成员共享并添加到他们的文档中去。通常还有每天进行修改。软件应该考虑到这一点，这不仅有助于确保提供一个标准化的终端产品，还有助于培养小组成员之间分享观点和知识的习惯。

当我在CSC（计算机科学公司）公司工作时，我曾经利用混合结果对微软的Agent和文本到语言技术作过实验。我始终认为它为新用户了解我的系统的一些特性提供了一个精彩的方法。一些人可能还记得Word 97中小纸夹字符的闪光效果是多么令人讨厌，这个比那个更令人讨厌。

使用Agent，你可以将你的的字符在屏幕上移动，指向一个下拉框，编程的方式打开下拉列表框并可以告诉你提供的选项有哪些。我为我的软件创建了一个向导，让学舌着Peedy指向列表框，输入文本向列表框，改变屏幕，引导终端用户在数据库中创建记录的整个过程。

使用Agent使我避免了编写大量冗长乏味的文档，其中将会详细地介绍创建，保存和修改新纪录的操作步骤。它可以使我得工作更具创造性，让我以一种积极和有益的方式参与文档编制工作。创造性是大多数开发人员具备的素质而且是使他们成功的一个关键因素。在开发文档时，可以而且应该考虑创造性，这取决于你所在公司的标准和期望。

我收到的关于我的微软Agent实验的唯一的反馈信息是有些人有太多的空闲时间而且没有认真看待这件事，至少有一部分是因为滑稽的外观字符。构建它不需要大量额外的工作，但是它确实要求我们学习一些新的编码技术。我们部门的某个人接受培训是件愉快的事情，我可以告诉他们使用向导导游。可能微软很有超前意识并有大量令人尊敬的高级人才，这类技术总有一天仍将成为主流技术。

最近，作为50年结婚纪念日的礼物，我为父亲构建了一台计算机。我编制了一些标记为重要的PC说明请阅读字样的说明文档并留在桌子上面一个快捷操作方法。同时我还创建了一个音频文件介绍了计算机的特性和使用说明。我问他是否看过我写的使用说明，但是它告诉我他按照计算机使用音频向导进行操作。

这是一些替代文档的例子。以笔者的拙见，在今天的公司环境下，编制文档的新方法远未充分利用而且低估了新方法的简单性和潜在的影响。

尽管编者文档很麻烦，但仍旧需要开发文档化的软件包，不过已经出现了大量有用的文档编制工具，它们被设计用于完成特定的文档编制任务。

#8：如果可能的话，尽量自己完成文档编制

编制文档的最佳人员就是开发者自己。毕竟，还有谁比系统开发者更理解系统功能？

如果你是一名系统开发员，那么你也可能是一名高明的程序设计员。但是仅仅在程序员面前提到文档这个词，他就会作出“你开玩笑吧”的样子。如果强制的话，程序员也会完成他们的文档编制工作，或者至少会试图编制一些将会转给文档人员的资料文件。我知道，我见过很多这种情况，甚至我自己也有这种错误。

这是一个现实的尴尬，因为一个拥有良好的编制文档能力的程序员是公司十分有价值的资产。如果是另外一个人为你得项目编制的文档，那么在性能评价时你的项目经理会记住什么？我猜肯定不是你应该得到晋升，加薪或得到奖金。

虽然不是很有趣，但是当正确的编制时，文档还是很有益的。不仅可以使你提供给客户一个更好的完整项目，而且还可以减少将来你不得不提供的支持时间。同时还可以减少服务中心的支持次数和维护时间。

当我在CSC工作时，我有机会作为项目负责人设计和开发我们的全球报告系统和基础设施。我能够直接看到文档的另一方面。我们小组中有一位很好的程序员，他负责的工作是水晶报表API设计和定制功能开发。很明显对我来说他的知识是唯一的，所以需要与其他小组成员分享，有什么更好的方式让大家分享他的知识而不仅仅是将他的工作文档化？我没有完全成功地使他向大家解释他的工作达到其他人可以按照他的方法自己做的地步。不过，他的确列出并解释了函数名称，如何使用它们，它们如何工作以及它们是如何实现的，这对于其他小组成员是很有帮助的。

在编码领域像存在一条不成文的规定，程序员的编程能力与他所承担的文档编制工作量成反比。

在我的职业生涯中给于我的第二大称赞是，当我为我们的全球技术支持小组作报告时，我不得不创建并提供一份关于如何创建报告服务器的文档。其中我们的一位数据库管理员是一位来自英国的小伙子，他也出席了报告会。在看了我写的如何创建一个报告服务器的文档后，他解释并评价说文档写的太好了，按照我的文档说明他完全自己能够构建一个报告服务器。诸如此类的语言使我的辛苦工作变得很有价值。对主要的项目工作来讲，这并不值得赞美——但是对文档来说这是值得的。

#9：协调终端用户文档与内部/系统文档的编制

如果同时编写用户文档和系统文档，这将会节省你的时间。你可以在两者之间共享一些信息并减少信息遗漏。即使你不想这么做或者这两个文档之间不适宜分享信息，你也可以从其中的一个文档的主题中获益，这将有助于你在另一个文档中包含补充的文档。

#10：遵循部门或公司的文档标准

创建和遵循标准格式和指南。这将有助于确保避免丢失重要信息并便于系统用户阅读。

在洛杉矶休斯飞机公司工作时，有一次我曾经和一位专业的文档专家共同为我的系统编写文档，结果相当成功。格式是遵循部门标准而且结果比我希望的要好。达到这种结果需要大量时间和精力。文档专家需要访问我的测试系统并与我接触，因此我可以回答他的问题。这样做的代价是昂贵的，并不是所有公司都有这样的资源来收集专业文档，但是如果系统开发人员能够核实终端产品的重要信息没有被曲解或者遗漏，那么结果也可以卓越。

十分幸运，我曾经有一位工程师，他在编写文档方面也很出色。他能够理解设计、开发的系统是做什么的，通过实际使用系统来发现它是如何工作的，然后填写说明文档中的空格。你可能没有这么幸运。

在今天这个全球市场，销售和支持的时代，文档也应该遵循国家或地区标准。我经常需要重复读好多遍中国制造的电子齿轮的使用手册，因为它实在太难翻译了。它是用中式英文写的，对于一些句子我不得不停下来，然后试着理解它的意思。我通常只是像斯库比-杜那样想一想，然后移到手册的其它部分。

用英语写成的文档是否能够方便中国人学习理解呢？我想文档中的英语对说汉语的人来说可能会跟听英语的感觉一样。为了使得文档更易于理解，应该找到并用一位专业的翻译人员来翻译，从而可以避免翻译中遗漏重要信息。

我还应该说得更明白一点。你的文档应该避免拼写错误和语法错误。记住使用拼写检查程序来查找错误。每当我重读文档时，我总是吃惊于怎么会出现如此多明显的拼写错误和简单疏漏。

文档编写人员

如果我还没有使你信服编写良好的文档对你和你的老板都十分有益的话，那么下面的事实将会让你感到舒服些——编写良好的文档决不仅仅是仆人的任务。当将你的工作文档化时，你也就是一名文档编写人员。希望这些技巧将会有助于你避免出现这些浪费时间和破坏性的问题，对于你和你们的服务中心的技术人员来数，这些问题是常见的。

作者按：

这是我第一次正式发表文章。在这里我要感谢Sonja Thompson和Mark Kaelin给我这个机会让我同大家分享我的想法。我不确定为什么Mark决定给我这个机会来讨论这个令人畏缩的主题作为我的第一篇文章。可能是如他指出的如果我能写一篇关于文档的令人感兴趣的文章的话，我就可以写几乎是任何东西了！我很高兴他这样说。我对他和TechRepubic的感谢难以用语言来表达。

一个无名的读者现在已经成为一名无名的作者。

额外参考：

“…有关文档的四个最重要的属性是它的内容，维护，可获得和使用例子。”第58页

http://www.site.uottawa.ca/~tcl/gradtheses/aforward/aforward_thesis.doc

文档的重要性

http://searchsmb.techtarget.com/originalContent/0,289142,sid44_gci1251087,00.html

责任编辑：德东

查看本文国际来源