科技行者

行者学院 转型私董会 科技行者专题报道 网红大战科技行者

知识库

知识库 安全导航

至顶网软件频道应用软件软件文档的价值和问题

软件文档的价值和问题

  • 扫一扫
    分享文章到微信

  • 扫一扫
    关注官方公众号
    至顶头条

软件文档的首要目标是表达系统的技术元素和用法。软件文档的次要目标是提供一项开发工作的需求、决策、动作、角色和责任的书面记录。只有在你意识到这两个目标时,你的文档才能提供有意义的信息……

作者:Scott Withrow 来源:dnet  2007年9月9日

关键字: 软件文档 价值 问题

  • 评论
  • 分享微博
  • 分享邮件

在本页阅读全文(共19页)

像很多同行一样,我理解软件文档的价值。不幸的是,在开始一项任务之前我却很少阅读软件文档。相反,我通常会模仿目光短浅的父母,他们在组装好孩子的自行车时,总会多出一些零件来。

如果我们知道软件文档的价值,那么为什么不经常使用它呢?对于新手,大多数软件文档都存在很多下面提到的这些问题:

• 糟糕的语法和/或拼写错误的词语

• 不完整

• 过期或不准确

• 篇幅太长

• 首字母缩写没有解释或术语不专业

• 难于找到信息或在文档中定位

存在这些问题的主要原因是软件文档通常没有被给予足够的重视。项目预算被迫将主要活动花在了开发工作上,在那里管理层很容易看到他们的收益。值得投入成本的文档工作通常都是主观的,而且通常被刻画为需要避免的成本,因为它们被认为不能产生投资回报(ROI)。很多项目经理将客户所需要的最少文档看作是“镀金”。

软件文档的另外一个麻烦来源是文档的作者。很多应用程序开发经理觉得软件文档是开发工作的一个标准部分,因此,要求他们的开发人员在编码时也编写软件文档。

虽然这在理论上是说得过去的,但是不应该将开发人员看成文档作者。很简单,技术人员只被培训如何开发,而没有被培训如何写文档。为了解决这一问题,很多应用程序开发经理尝试通过聘请一些技术性写手或商业分析人员来提高他们的软件文档的质量。这就导致出现了一个相反的问题:技术写手和商业分析人员通常只有有限的技术技能。

解决方案依赖于文档,文档应该迎合其潜在读者的口味。这方面的通用规则是要求使用一个协同工作方法来编写文档,这种方法允许开发人员和写手发挥他们的长处。例如,如果潜在的读者是系统设计人员,那么开发人员应该提供详细的输入,但是允许技术写手去组织和编辑内容以使文档符合语法。

不管潜在的读者还是被选中的读者,软件文档的质量与其可使用性相关,以下六个属性可以用来测量软件文档的可使用性:

• 适用性:文档提供了相关的信息吗?

• 合时性:文档所提供的是当时的信息吗?

• 正确性:文档所提供的信息正确吗?

• 完整性:文档是不是足够详细?

• 可用性:文档随手可用吗?

• 可使用性:能够快速直观地找到所需的信息吗?

软件文档的首要目标是表达系统的技术元素和用法。软件文档的次要目标是提供一项开发工作的需求、决策、动作、角色和责任的书面记录。只有在你意识到这两个目标时,你的文档才能提供有意义的信息

查看本文来源

    • 评论
    • 分享微博
    • 分享邮件
    闂傚倷绶¢崣搴ㄥ窗閺囩偐鏋庨柕蹇嬪灪婵ジ鏌曡箛瀣偓鏍綖閿燂拷

    濠电姷顣介埀顒€鍟块埀顒€缍婇幃妯诲緞閹邦剛鐣洪梺闈浥堥弲婊勬叏濠婂牊鍋ㄦい鏍ㄧ〒閹藉啴鏌熼悜鈺傛珚鐎规洘宀稿畷鍫曞煛閸屾粍娈搁梻浣筋嚃閸ㄤ即宕㈤弽顐ュС闁挎稑瀚崰鍡樸亜閵堝懎濮┑鈽嗗亝濠㈡ê螞濡ゅ懏鍋傛繛鍡樻尭鐎氬鏌嶈閸撶喎顕i渚婄矗濞撴埃鍋撻柣娑欐崌閺屾稑鈹戦崨顕呮▊缂備焦顨呴惌鍌炵嵁鎼淬劌鐒垫い鎺戝鐎氬銇勯弽銊ф噥缂佽妫濋弻鐔碱敇瑜嶉悘鑼磼鏉堛劎绠為柡灞芥喘閺佹劙宕熼鐘虫緰闂佽崵濮抽梽宥夊垂閽樺)锝夊礋椤栨稑娈滈梺纭呮硾椤洟鍩€椤掆偓閿曪妇妲愰弮鍫濈闁绘劕寮Δ鍛厸闁割偒鍋勯悘锕傛煕鐎n偆澧紒鍌涘笧閹瑰嫰鎼圭憴鍕靛晥闂備礁鎼€氱兘宕归柆宥呯;鐎广儱顦伴崕宥夋煕閺囥劌澧ù鐘趁湁闁挎繂妫楅埢鏇㈡煃瑜滈崜姘跺蓟閵娧勵偨闁绘劕顕埢鏇㈡倵閿濆倹娅囨い蹇涗憾閺屾洟宕遍鐔奉伓

    重磅专题
    往期文章
    最新文章