虽然编制文档并不是众多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：给出示例

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

#3:不要指望假设

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

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

#4：预期可能的问题

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

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

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

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

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

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

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

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

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

#5：测试你的文档

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

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

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

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

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

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

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

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

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

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