`
liyiye
  • 浏览: 426944 次
  • 性别: Icon_minigender_1
  • 来自: 广州
社区版块
存档分类
最新评论

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

10技巧创建软件开发文档

7步项目生存期来源:WikipediA

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

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

#2:给出示例

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

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

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

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

开启先前版本

图 B

10技巧创建软件开发文档

选择开始|控制面板

图 C

10技巧创建软件开发文档

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

图D

10技巧创建软件开发文档

左键单击系统保护选项卡

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

图 E

10技巧创建软件开发文档

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

左键单击滚动条并向下滑动只到在逻辑磁盘/分区中找到你要开启先前版本的那个分区。在本例中的逻辑磁盘名为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

分享到:
评论

相关推荐

    创建软件开发文档10技巧

    ### 创建软件开发文档的10个实用技巧 #### 技巧1:利用图形化文档减少文字叙述 在软件开发过程中,编写文档是一项重要的任务。为了提高文档的易读性和实用性,建议采用图形化的形式来表达复杂的概念。正如一句老话...

    软件开发文档(模版),接口文档

    在软件开发过程中,接口文档和开发文档是至关重要的组成部分,它们为团队间的沟通、协作以及项目的规范性提供了保障。...通过阅读和参考提供的“软件开发文档(模版)”,开发者可以更好地理解和实践这些原则。

    软件开发文档模板[全套]

    这套“软件开发文档模板[全套]”提供了从项目启动到最终交付的所有阶段所需的指导文件,对于任何软件公司来说都是宝贵的资源。以下将详细阐述这些文档的重要性和内容。 1. **需求规格说明书**:这是项目开始时的第...

    参考资料-软件开发文档编写规范.zip

    在软件开发过程中,文档是沟通、协作和质量保证的关键元素。"参考资料-软件开发文档编写规范.zip" ...这份"参考资料-软件开发文档编写规范.doc"将为开发者提供一个详细的指南,帮助他们掌握编写专业文档的技巧和流程。

    software-diagram1-7.rar_C 软件开发_软件开发 c_软件开发文档_软件文档

    3. **软件开发文档** - **需求规格书**:详细描述软件应实现的功能和性能要求。 - **设计文档**:记录软件架构、模块设计和接口说明。 - **编码规范**:规定代码的格式、命名规则和注释标准,提高代码质量。 - *...

    Adobe Acrobat 10 开发说明文档及实例

    Adobe Acrobat 10 开发说明...通过对这些知识点的深入学习和实践,开发者可以掌握Adobe Acrobat 10的开发技巧,创建出满足特定需求的PDF解决方案,无论是桌面应用、Web服务还是移动平台,都能充分利用PDF的强大功能。

    软件开发文档模板.doc

    《软件开发文档模板详解》 在软件开发过程中,详尽且规范的文档是项目成功的关键要素之一。软件开发文档模板提供了整个开发流程的结构化指南,涵盖了从项目启动到最终交付的所有阶段。以下是对该模板中各个部分的...

    Linux_soft_develop.rar_Linux 开发_linux_嵌入式 linux_嵌入式软件开发_软件开发文档

    软件开发文档通常会包含详细的步骤、示例代码、调试技巧和最佳实践。例如,它可能会介绍如何使用GDB进行远程调试,或者如何使用SystemTap进行动态分析。此外,文档可能还涵盖了版本控制工具(如Git)的使用,项目...

    openoffice中文开发文档

    这份"openoffice中文开发文档"针对的是OpenOffice的Web开发项目,对于想要在网页环境中利用OpenOffice功能的开发者具有很高的参考价值。 1. OpenOffice API:OpenOffice的API分为Java和UNO(Universal Network ...

    软件工程文档模板[几乎全了]

    5. **计算机软件开发文档编写指南.zip**:这可能是一份详细的指南,教导如何编写各种类型的软件开发文档,包括文档的结构、内容要求和编写技巧。遵循这份指南能帮助新手理解文档编写的重要性,提升文档编写技能。 ...

    东集小码哥PDA开发文档

    【东集小码哥PDA开发文档】是一份详尽的指南,专为开发者提供关于如何在东集小码哥PDA上进行软件开发的知识。这份文档覆盖了从基础概念到高级技术应用的各个方面,旨在帮助开发者充分利用这款设备的功能,进行高效、...

    软件开发帮助文档合集

    在软件开发过程中,掌握各种技术文档是至关重要的。这个名为“软件开发帮助文档合集”的压缩包包含了几个关键领域的核心参考资料,旨在协助开发者理解和运用不同的技术。以下是这些文档的主要内容和知识点: 1. **...

    2019WPS二次开发文档API.zip

    WPS文字部分的开发文档,详细介绍了如何利用API进行文档操作,如创建、打开、保存文档,以及插入、编辑文本、图片、表格等元素。此外,还包括对样式、模板的管理,以及宏的编写和应用,帮助开发者实现自动化处理文档...

    linux开发文档大全(10个文档一起打包共享)

    Linux开发文档大全是一个集合了多个核心工具和技术的资源包,主要针对Linux系统中的编程和开发工作。这个压缩包包含了10个重要的文档,涵盖了从基本的Linux编程到高级的自动化构建工具,为开发者提供了全面的学习...

    soui 开发文档说明

    SOUI 是一款由启程软件开发的C++库,它致力于提供一个基于Direct UI技术的高效、轻量级界面开发框架。Direct UI是一种设计模式,用于实现用户界面的直接绘制,它使得开发者可以更加灵活地控制界面元素的呈现和交互。...

    酒店餐饮管理(VC++源代码 + 软件开发文档)

    《酒店餐饮管理(VC++源代码 + 软件开发文档)》是一个综合性的学习资源,旨在帮助学生或开发者理解并实践如何利用VC++进行软件开发,特别是在酒店餐饮管理领域的应用。这个压缩包包含了完整的源代码和软件开发文档,...

    程序开发功能需求文档模板.docx

    在软件开发过程中,一份详尽且规范的功能需求文档是项目成功的关键。本文将深入解析"程序开发功能需求文档模板",并提供相关指导,帮助开发者和项目经理理解如何有效地制定和使用此类文档。 1. 引言 引言部分是需求...

    软件开发-文档模板(国标)

    在软件开发过程中,文档起着至关重要的作用,它不仅是团队沟通的桥梁,也是项目管理和质量保证的基石。"软件开发-文档模板(国标)"是一个按照国家相关标准编写的文档模板集合,虽然有些老旧,但对于理解和遵循规范化...

Global site tag (gtag.js) - Google Analytics