10技巧创建软件开发文档(转)

虽然编制文档并不是众多IT专业人员选择职业的真正原因，但是足够的激情、勤奋工作和注意细节将会使你成为老板的一份更具价值的资产并能够提升你的履历。

本文我们介绍了取自10 Things博客中的文章《创建软件文档的10项技巧》。该博客主要面向应用开发专业人员，但是项目经理和管理人员也可以从他们的智慧中获益。

Alan Norton从事软件系统开发和相应软件项目文档编制工作很多年。我们可以从他的多年从业经验中获益。

坦白地讲，没人想写，没人想读或者实际上是不得不作这项工作。我想说的是软件开发中的文档编制，通常定义为软件生存期的倒数第二步。虽然编写文档可以而且应该出现的软件生存期的任何阶段，但是本文我们将集中在文档编制阶段。需要注意的是我们要讨论的文档包括两部分：终端用户文档和系统/内部文档。

项目生存期

在准备这篇文章而做一些研究时，我找出了Petrocelli/Charter 1976年出版的Anthony Ralston 和 Chester L.Meek编辑的计算机科学百科全书。可以明确地是这是第一版的经典，但是有一些东西是永恒的，其中在文档词条关于文档的描述为：

“文档是开发和应用基于计算机的系统的重要部分。在一些商业组织，20%到40%的开发工作量用于新系统的文档编制，其中记录了新系统是如何工作的以及是如何开发的。”作者K.R.London。

我对于这个定义在今天的正确性感到好奇，如果是真的话，那么为什么媒体没有给与文档应该的关注。在项目生存期我们找不到很多关于文档花费的信息（如 图A）。我猜测可能是这些花费经常被低估或没有进行合理的收集。从事工作系统开发的IT专业人员，很多可能会将文档的实际花费看作是件尴尬的事或者认为这 反映了他们不良的生产率和工作。

对项目生存期文档阶段的重要性的看法，可能依赖于你在IT组织的角色。如果你是经理或项目小组组长，那么你会认为文档对于项目的成功是十分重要的。如果你处于一个非管理职位，那么你会认为编制文档是件恼人的麻烦事，因为它妨碍了你的实际工作。尽管下文的10项技巧主要面向后一类人员，但是项目经理和管理人员同样也可以从中获益。

图 A

7步项目生存期来源：WikipediA

#1: 如果可能尽量编制图形文档

有句古老的格言说是一幅图胜过千句言，意思是说通过使用图形表达你的观点，将会使文档的长度和复杂性减到最小。系统用户喜欢使用图形，图表，表格和列表进行快速查找参考。

#2：给出示例

例子是终端用户快速掌握他们可能没有完全理解的概念的最好方式。同时对学习使用新软件的终端用户来说，例子还是他们坐下来更容易地处理一项新的挑战好方式。下面是一个带有图片的文档的例子：

Vista商业、终极和企业版中的先前版本

先前版本是微软用于存储一个文件影印的术语。如果你正在编辑一个文档或任何其它劳动密集型的项目且意外地丢失了部分或全部工作，那么你可以返回到一个先前版本。先前版本可以看作是以自动的方式及时地对以前的文件拍下的快照。

但是首先我们需要配置Vista，以便开启你想要用来恢复丢失文件的先前版本功能（图B至图E）逻辑磁盘/分区。

开启先前版本

图 B

选择开始|控制面板

图 C

左键单击高级系统设置——如果提示UAC（用户账号控制）左键单击继续。

图D

左键单击系统保护选项卡

注意：默认情况下，Vista逻辑磁盘/分区已经开启。在完全清楚这样做的后果后在改变这个设置。

图 E

向下滑动滚动条选择逻辑磁盘

左键单击滚动条并向下滑动只到在逻辑磁盘/分区中找到你要开启先前版本的那个分区。在本例中的逻辑磁盘名为Documents。左键单击逻辑磁盘名前面的单选按钮选中。

注意：影印文件的创建基于系统创建恢复点的时间和频率。根据Vista的帮助文件，典型情况是一天一次。

单击应用然后单击确定关闭系统属性窗口。单击文件|关闭或单击控制面板|系统窗口右上部的红色X按钮关闭它。

为了恢复一个文件的先前版本，你可以右键单击浏览窗口中的文件名然后左键单击恢复先前版本即可。

注意：一旦文件的一个影印被恢复后，就不能用于二次恢复。在下一个系统恢复点创建之前，不能创建另外一个影印文件。这就意味着任何在下一个系统恢复 点保存的文件不能恢复到你前面使用的那个先前版本中去。应该加强练习注意在使用了恢复先前版本选项后直到下一个恢复点发生和另外一个影印文件可以创建后在 保存文件。

#3:不要指望假设

即使你知道你的目标用户群，也需要编写应用文档以便任何一个具备基础计算机技能的人都可以阅读并学会如何正确的使用新系统。可能的情况下，应该提供 一步一步地操作指令。但为了避免混乱，可以考虑将文档放在附录中，单独的章节中或通过超链接访问它们。如果你在编写文档，改变一下你的思维方式从而使你可 以站在新系统用户的角度考虑问题。起初，这可能有点困难，但是只要你注意细节并对将所有特性和功能变成文档，你就可以创建一个良好的文档，而不用假定用户 可以自己领会你没有包括进去的信息和过程。

不用假定终端用户能够理解所有的缩写词，这些缩写词往往扰乱了IT的美景。在第一次提出一个新的缩写时，应详细说明该缩写代表什么意思。

#4：预期可能的问题

在测试系统时，应该尽你所能用各种方法测试你的软件。如果你的软件存在明显的错误( 开发人员喜欢称为错误，终端用户称它们为漏洞)，那么应该将解决办法编写进文档并提供给用户和服务台。这样不仅可以省去终端用户的诸多问题还可以省去服务台大量的额外电话咨询。

任何生存期较长的系统，对在生存期间不可避免的事件应该编写成文档。

当系统或网络实效时，可以使用什么样的工作区？

如何从一个严重的内存溢出，一个硬盘崩溃或数据库崩溃中恢复？

一个对于你的系统一无所知的人如何启动系统并运行它？

你的文档应该预期这些问题并提供一个详细的计划和指令用于系统恢复。

替代你的人知道到哪里找到你的文档和任何其它购买的供应商的应用文档吗？所有这些文档应该整齐的组织在一起并存放在一个安全容易找到的地方。

预期问题的另一个很好的例子是Y2K千年虫问题及其解决方法。20世纪90年代后期媒体开始报告由于在合法系统中只用两位数字存储年份所以系统和软 件可能会失效。这个问题被预先考虑到并投入了大力努力在问题出现之前解决它。开发的软件对2000年1月1日之前的年份被设计成并确保与Y2K相兼容的年 份表示方式。结果取得了显著成功。除了少部分报告的问题外，对IT社区来说，2000年的新年是一个欢乐的时刻并不是一个大灾难日。尽管我们派出大量专门 人员随时待命以应对突发的问题。

在你的文档中也可以用同样的方法预期可能出现的问题。同时千年虫问题还显示了应该不断的对文档进行更新。修改系统/内部文档来说明软件和系统的Y2K兼容性或不兼容性。对于以前的合法系统，找到工作区并将之文档化。

#5：测试你的文档

坐下来查看一遍你的说明。如果你的文档是在介绍如何构建一个服务器，一个网络或任何其它IT系统，那么最好从一个空白的地方起步，一切从头开始构建。毫无疑问，你肯定会发现遗漏了某些东西或者其中一些操作说明不是很清楚。

在发布之前，与一些没有通知过但很忠实同事共同检查文档以获得他们的反馈信息。让他们测试你的文档。

当你与一个人一起坐下来第一次检查你得软件和文档时，你将会对你所学到的东西感到吃惊。大量对你来说是很明显的软件特性但对另外一些诚实且乐意与你共同工作的人可能并不明显。仔细的观察你得实验者在操作软件时做了些什么，寻求反馈信息并做好记录。

我还记得在我的一个项目测试期间得到反馈信息，是用电子邮件写给我的，因此我可以逐条阅读。我头脑中第一个想法是“这样做要花多少时间？”你可能会 将这些评论看作是批评性的或针对个人的。不要在犯这样的错误了。现在回头想想，我本应该实现有益的批评者提到的更多被遗漏的特性。

利用这个机会可以对你得项目进行最后的完善。编制文档过程中的反馈信息可以帮助使得整个项目更加成功。

我正在为Foxconn 975X7AB-8EKRS2H主板写评论，碰巧在使用手册中发现两处错误。我并不是第一个评论Foxconn板的人。Foxconn忽略了错误且所有其它评论人员也都忽略了错误。其中一个错误绝非是微不足道的。

手册中显示清除CMOS跳线设置的正确位置的图表是错误的。我知道是因为当我们翻转主板以验证散热片的位置是否正确时，跳线就跌落了。我根据手册中的说明将跳线放回原处，但计算机的加电自检功能失效。在仔细查看了主板上的微型图表后，我发现了错误并修改了放错的跳线。

那个时候我正和一位来自Foxconn公司的技术人员合作共事，这位技术人员很友好的回答了我的问题，然后我告诉他出现的错误。像这样的文档错误很容易被忽略，但可能给生产商带来潜在的巨大代价。要不是在翻转主板时跳线很松以至于脱落下来，我也不会发现这个错误。

#6：将你的工作尽量人性化

你曾经阅读过多少次用户手册？又有多少次想过在另一方编制手册的真实一个生活中的人吗？——或者用户手册是由计算机自动编制的吗？虽然你不是在创作一部丰富多彩的小说，但是尽量使文档人性化一些，使其具有一些你得个性，这样读者在阅读手册时会感觉更舒服一些。

#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

责任编辑：德东