Builder.com.cn-管理职涯-优秀软件文档的必备要素
来源:百度文库 编辑:神马文学网 时间:2024/03/29 03:27:28
优秀软件文档的必备要素
作者: Builder.com
2005-01-14 10:18 AM
和大多数同行一样,我明白软件文档的重要性。不幸的是,在任务开始前我很少阅读文档。相反,我常常像视线不清的父母一样,在装配好他们孩子的自行车之后,还落下一两个零部件没装上。
[被屏蔽广告]
如果我们明白文档的重要性,那为什么我们不更经常用它呢?然而,许多软件文档存在以下问题:
· 错误的语法和/或拼错的词语
· 不完整
· 过时或不准确
· 过于冗长
· 未经解释的缩略语或专用术语
· 查找信息困难
存在这些问题的主要原因是软件文档常常被退居次位。工程预算迫使我们优先考虑开发过程中的主要活动,也就是那些可以看得到利润的地方。编写文档需要成本,因而它常常成为一项主观上的活动,而且通常被认为没有重要作用,应该尽量避免。许多项目经理认为客户不需要文档,它只是用来装点门面的。
软件文档质量差的另外一个原因在于文档撰写者。许多应用程序开发经理认为软件文档的编写是软件开发过程的一个标准组成部分,因此要求开发人员在编码的过程中产出文档。
尽管这种做法在理论上行得通,但它没有考虑开发人员编写文档的能力。简单来说,技术人员是用来开发软件而不是编写文档的。为了解决这个问题,许多应用程序开发经理雇佣专业技术文档编写者或业务分析师,以期改进软件文档的质量。但这又遇到了另一个难题:专业编写者及业务分析师的技术水平有限。
解决这个问题要考虑需要编写的文档以及文档的预期读者。一般的规则是,写文档需要团队协作,这样就允许开发人员和文档编写者利用彼此的长处,取长补短。例如,如果预期读者是系统设计师,开发人员需要提供技术细节,然后文档编写者按照正确语法组织和编辑内容。
不考虑预期读者或专门编写者,软件文档的质量取决于其可用性,可从以下6个方面去评价其可用性:
· 应用性:文档是否提供相关信息?
· 及时性:信息是否及时?
· 准确性:信息是否正确?
· 完整性:文档是否足够详细而又不会太过拘泥细节?
· 可得性:文档是否随时可得?
· 可用性:你能否很快凭直觉就找到所需信息?
软件文档的最主要目标是传达一个系统的技术要素和使用方法。第二个目标是提供软件开发过程中的需求,决策,行为,角色和责任的书面记录。只有实现了这两个目标,软件文档才真正提供了有意义的信息。
作者简介:Scott Withrow有20多年的IT行业经验,包括IT管理,网络开发管理和内部咨询应用分析方面的经验。
_xyz
作者: Builder.com
2005-01-14 10:18 AM
和大多数同行一样,我明白软件文档的重要性。不幸的是,在任务开始前我很少阅读文档。相反,我常常像视线不清的父母一样,在装配好他们孩子的自行车之后,还落下一两个零部件没装上。
[被屏蔽广告]
如果我们明白文档的重要性,那为什么我们不更经常用它呢?然而,许多软件文档存在以下问题:
· 错误的语法和/或拼错的词语
· 不完整
· 过时或不准确
· 过于冗长
· 未经解释的缩略语或专用术语
· 查找信息困难
存在这些问题的主要原因是软件文档常常被退居次位。工程预算迫使我们优先考虑开发过程中的主要活动,也就是那些可以看得到利润的地方。编写文档需要成本,因而它常常成为一项主观上的活动,而且通常被认为没有重要作用,应该尽量避免。许多项目经理认为客户不需要文档,它只是用来装点门面的。
软件文档质量差的另外一个原因在于文档撰写者。许多应用程序开发经理认为软件文档的编写是软件开发过程的一个标准组成部分,因此要求开发人员在编码的过程中产出文档。
尽管这种做法在理论上行得通,但它没有考虑开发人员编写文档的能力。简单来说,技术人员是用来开发软件而不是编写文档的。为了解决这个问题,许多应用程序开发经理雇佣专业技术文档编写者或业务分析师,以期改进软件文档的质量。但这又遇到了另一个难题:专业编写者及业务分析师的技术水平有限。
解决这个问题要考虑需要编写的文档以及文档的预期读者。一般的规则是,写文档需要团队协作,这样就允许开发人员和文档编写者利用彼此的长处,取长补短。例如,如果预期读者是系统设计师,开发人员需要提供技术细节,然后文档编写者按照正确语法组织和编辑内容。
不考虑预期读者或专门编写者,软件文档的质量取决于其可用性,可从以下6个方面去评价其可用性:
· 应用性:文档是否提供相关信息?
· 及时性:信息是否及时?
· 准确性:信息是否正确?
· 完整性:文档是否足够详细而又不会太过拘泥细节?
· 可得性:文档是否随时可得?
· 可用性:你能否很快凭直觉就找到所需信息?
软件文档的最主要目标是传达一个系统的技术要素和使用方法。第二个目标是提供软件开发过程中的需求,决策,行为,角色和责任的书面记录。只有实现了这两个目标,软件文档才真正提供了有意义的信息。
作者简介:Scott Withrow有20多年的IT行业经验,包括IT管理,网络开发管理和内部咨询应用分析方面的经验。
_xyz
Builder.com.cn-管理职涯-优秀软件文档的必备要素
Builder.com.cn-管理职涯-注定失败职员的十大致命缺陷
Builder.com.cn - 编程 - 如何避免软件开发中不兼容的设计方法
Builder.com.cn - 管理&职涯 - 如何界定项目风险
Builder.com.cn-编程-避免六个常见的开发错误
Builder.com.cn - 新闻 - Ubuntu的成功之道
OSGi: Eclipse的根基 - 开发者在线 - www.builder.com.cn
Builder.com.cn - 编程 - 利用Anchor和Dock属性管理WinForm控件
info.sugoo.com - /CN/Ebook/模板资源/办公管理文档/
Builder.com.cn-编程-Visual Studio 2005 中的新的 DataSet 功能
Builder.com.cn - 数据库 - [Oracle]用OraKill结束失控的O...
Builder.com.cn - Web技术 - Web 2.0:打造开放参与的架构
Builder.com.cn-数据库-选择MySQL还是SQL Server
Builder.com.cn - 新闻 - Web攻击者隐藏性变得更高
每日管理建议:如何尽快得到确定的答复 | 职场管理 | reuters.com.cn
每日管理建议:保护自己的好点子 | 职场管理 | reuters.com.cn
软件项目需求分析的文档都包括哪些内容 - CSAI.cn软件工程
Builder.com.cn - Web技术 - Web 2.0和无上下文数据
Builder.com.cn - 编程 - 在Spring中使用JDK Timer进行任务...
Builder.com.cn - Web技术 - 如何利用CSS控制文本属性
软件管理和软件开发文档的关系?(转自CSDN)
软件管理和软件开发文档的关系?(转自CSDN)_iSsay
编写优秀技术文档的技巧,中国软件网,软网,网络学院
软件项目生命周期中的文档管理