1、信息系统的文档,是系统建设过程的“痕迹”,是系统维护人员的指南,是开发人员与用户交流的工具。规范的文档意味着系统是按照工程化开发的,意味着信息系统的质量有了形式上的保障。文档的欠缺、文档的随意性和文档的不规范,极有可能导致原来的开发人员流动以后,系统不可以维护、不可以升级,变成一个没有扩展性、没有生命力的系统。所以,为了建立一个良好的信息系统,不仅要充分利用各种现代化信息技术和正确的系统开发方法,同时还要做好文档的管理工作。本节主要讨论的内容:一、信息系统文档的作用与类型二、信息系统各类文档的内容三、信息系统文档的编制与管理,第八章、信息系统的文档管理,一、信息系统文档的作用与类型,在软件工程
2、的学科领域里,文档和程序加在一起被合称为软件。文档与程序的区别在于前者是人可读的,后者主要是机器用来执行的。如果将源程序加上注释,也可称为文档的一部分。本节主要介绍:l、 信息系统文档的作用2、信息系统文档的类型,l、信息系统文档的作用,这里指的信息系统的文档,不但包括应用软件开发过程中产生的文档,还包括硬件采购和网络设计中形成的文档;不但包括上述有一定格式要求的规范文档,也包括系统建设过程中的各种来往文件、会议纪要、会计单据等资料形成的不规范文档,后者是建设各方谈判甚至索赔的重要依据。显然,文档的含义在信息系统学科领域里比软件工程学科宽泛。所以文档是软件的一部分,更是信息系统的一部分。没有文
3、档的软件,不称其为合格的软件;没有文档的信息系统,不称其为完整的信息系统。,文档在系统开发人员、项目管理人员、系统维护人员、系统评价人员以及用户之间的多种桥梁作用可从图8-1中看出。图8-1中列出了文档在信息系统建设和运行过程中的七种典型沟通作用:,(1)用户与系统分析人员在系统规划和系统分析阶段通过文档进行沟通。 (2)人员与项目管理人员通过文档在项目期内进行沟通。 (3)前期开发人员与后期开发人员通过书面文档进行沟通。 (4)系统测试人员与系统开发人员通过文档进行沟通。 (5)系统开发人员与用户在系统运行期间进行沟通。 (6)系统开发人员与系统维护人员通过文档进行沟通。 (7)用户与维护人
4、员在运行维护期间进行沟通。 上述七个方面是文档在沟通方面的主要作用,其实,文档还可以作为监理和审计的对象,作为开发其他信息系统的参照。,如果发生合同纠纷,文档还能体现出证据的作用。因为每份文档都是项目建设中有关成员的一种书面承诺。绝大多数文档都是需要签名的。而签名就表示对自己所签署的那部分文档内容的认可和承担责任。特别是用户提出的需求变更申请书必须妥善保管,这些文件在发生纠纷时往往能成为保护自己甚至索赔的重要依据。显然,文档的编制在信息系统的开发工作中占有突出的地位和相当的工作量。高效率、高质量地写作、分发、管理和维护文档对于充分发挥信息系统的效益有着重要意义。,2、信息系统文档的类型,信息系
5、统的文档有许多种分类方法:(1)按照产生频率分为一次性文档和非一次性文档。前者如系统分析说明书、系统设计说明书等,后者如开发过程中用户提交的需求变更申请书。非一次性文档还可以分为频率固定文档和频率不固定文档,频率固定文档有项目组月度开发报告、信息系统运行日志、运行月报等,频率不固定文档有会计单据、需求变更申请书、维护修改建议书等。一次性文档和频率固定的文档一般都有较固定的内容和格式,而频率不固定的文档由于发生的随机性,导致文档记录人员在撰写文档时的随意性。为了管理好这些频率不固定的文档,需要对这些文档予以编号,并尽可能地统一格式,以便做到规范管理。,(2)按照信息系统生命周期的阶段不同,可以划
6、分为:系统规划阶段文档,如系统可行性研究报告、项目开发计划书等;系统分析阶段的文档,如系统分析说明书等;系统设计阶段的文档,如系统设计说明书、需求变更申请书等;系统实现阶段的文档,如程序设计报告、系统测试报告、开发总结报告等;系统运行与维护阶段的文档,如用户手册、操作手册与维护修改建议书等。 本书的附录国家标准计算机软件产品开发文件编制指南基本上是按照软件的生命周期进行讲解的,可以作为信息系统文档的参照。,(3)按照文档不同的服务目的,可以将信息系统的文档分为三类:用户文档、开发文档与管理文档。用户文档主要是为用户服务的,开发文档主要是为开发人员服务的,管理文档主要是为项目管理人员服务 的。上
7、述三种文档的内容参见图8-2。 当然,图中的分类不是绝对的,比如项目开发计划对于开发人员来讲很重要;测试计划和测试报告对于管理人员来讲也很重要。这里要强调项目管理文档的重要性。项目管理文档是对项目计划、费用和问题进行监督的管理手段和项目建设过程进行记录的工具。这能使各级管理部门对项目的进展保持预见性,以便能及时发现和处理系统开发及维护过程中出现的问题。,二、信息系统各类文档的内容,尽管文档的重要性大家都大体知道,但在实际工作中,文档在编制和使用中仍然存在着许多问题,有待于解决。系统开发人员中较普遍地存在着对编制文档不感兴趣的现象。从用户方面看,他们又常常抱怨:文档售价太高、文档不够完整、文档编
8、写得不好、文档已经陈旧或是文档太多,难以使用,等等。各类文档究竟应该写哪些内容,说明什么问题,下面将大体按照信息系统生命周期的阶段,逐一介绍上面提到的各种文档。由于信息系统的分析与设计在信息系统的建设过程中非常重要,所以在对所有文档分别进行简单介绍后,专门给出了系统分析说明书和系统分析说明书的内容与参考格式。,本节内容:1、系统各类文档的内容简介2、系统分析说明书编写指南3、系统设计说明书内容指南,l、系统各类文档的内容简介,信息系统建设过程中主要文档有:系统开发立项报告、可行性研究报告、系统开发计划书、系统分析说明书、系统设计说明书、程序设计报告、系统测试计划与测试报告、系统使用与维护手册、
9、系统评价报告、系统开发月报与系统开发总结报告。下面对它们逐一介绍 :,(1)系统开发立项报告 在信息系统的正式开发前。用户单位必须提出要开发的新系统的目标、功能、费用、时间、对组织机构的影响等。如果是本单位独立开发或联合开发,这些内容形成的文档称做立项报告,用于向领导申请经费及支持等;如果是委托开发,则以任务委托或开发协议(合同)方式进行说明。立项报告主要包括以下内容:概述:概述现行系统的组织结构、功能、业务流程以及存在的主要问题。新系统的目标:开发新系统的意义和新系统实现后的功能、技术指标、安全和保密性、新系统运行环境等。经费预算和经费来源。 项目进度和完成期限。验收标准和方法。 移交的文档
10、资料。开始可行性研究的组织队伍、机构与预算。 其他有关需要说明的问题。,(2)可行性研究报告 可行性研究阶段的文档是可行性研究报告。在可行性研究报告中要说明待开发项目在技术上、经济上和社会因素上的可行性,评述为了合理地达到开发目标可供选择的各种可能实施的方案,说明并论证所选定实施方案的理由。可行性研究报告主要包括以下内容: 概述。 新系统的目标、要求和约束。 可行性研究的基本准则。 现行系统描述及现行系统存在的主要问题。 新系统对现行系统的影响。 投资和效益分析。 其他可选方案及与国内外同类方案的比较。 有关建议。,(3)系统开发计划书 可行性报告被批准后及在系统开发之前,需要拟定一份较为详细
11、的系统开发计划,以保证系统开发工作按计划保质保量按时完成。在开始计划书中,应该说明各任务的负责人员、开发的进度、开发经费的预算、所需的硬什及软件资源等。开发计划书应提供给项目管理人员,作为开发阶段评审的参考。对于项目计划的管理,可以采用Microsoft Project等项目管理软件进行辅助管理。系统开发计划书的主要内容如下: 概述:主要包括系统开发的主要目标、基本方针、参加人员、工作阶段和内容等。 开发计划:系统开发各工作阶段或子项目的任务、分工、负责人、计划时间(开始及结束时间)、人力与资金及设备消耗、实际执行情况等。可用工作进度表、甘特图、网络图及关键路径法等工具辅助管理。 验收标准:每
12、项工作完成后验收的标准(时间、资金、质量等)。 协调方法:信息系统开发中各个单位、阶段之间的衔接、协调的方法、负责人、权限等。,(4)系统分析说明书当信息系统的开发采用委托方式进行开发时,用户需求说明书(或叫用户需求报告)是开发单位与用户间交流的桥梁,同时也是系统设计的基础和依据。当采用独立开发或合作开发时,系统分析是系统开发中最重要的工作,其工作成果就是系统分析说明书(或叫系统分析报告)。系统分析工作的好坏决定了新系统的成败。从信息系统生命周期的角度来看,用户需求说明书就是系统分析说明书。系统分析说明书的主要内容一般包括: 概述。 系统需求。 新系统目标与新系统的功能。 新系统的逻辑模型。
13、新系统的运行环境。 新系统的验收标准与培训计划。,(5)系统设计说明书 在系统分析的基础上,根据系统分析说明书进行新系统的物理设计,并完成系统设计说明书(或叫系统设计报告)的撰写。系统设计说明书主要包括以下内容: 概述。 输入与输出设计。 总体结构。 计算机处理过程设计。 计算机系统配置。 接口及通信环境设计。 代码设计。 安全和保密设计。 数据库设计。 数据准备。,(6)程序设计报告 依据系统设计报告,进行程序设计工作。程序设计经调试通过后,应完成程序设计报告,以便为系统调试和系统维护工作提供依据。有了程序设计报告,就可以避免因程序员的流动造成系统维护工作的困难。程序设计报告的主要内容如下:
14、 概述。 程序流程图。 程序结构图。 源程序。 程序控制图。 程序注释说明。 算法。,(7)系统测试计划与测试报告为做好组装测试和确认测试,需为如何组织测试制定实施计划。测试计划应包括测试的内容、进度、条件、人员、测试用例的选取原则、测试结果允许的偏差范围等。 测试工作完成以后,应提交测试计划执行情况的说明。对测试结果加以分析,并提出测试的结论意见。系统测试是系统实施阶段的重要工作。系统测试报告主要内容如下: 概述:说明系统测试的目的。 测试环境:有关软硬件、通信、数据库、人员等情况。 测试内容:系统、子系统、模块的名称,性能技术指标等。 测试方案:测试的方法、测试数据、测试步骤、测试中故障的
15、解决方案等。 测试结果:测试的实际情况、结果等。 结论:系统功能评价、性能技术指标评价、结论。,(8)系统使用与维护手册 系统使用与维护手册是为用户准备的文档。有的系统比较大,将使用手册与维护手册分开。其中,系统使用手册(或叫操作手册)一般是面向业务人员的,他们是系统的最终使用者。系统维护手册(或叫技术手册)是供具有一定信息技术专业知识的系统维护人员使用的。系统使用与维护手册的主要内容包括: 概述:主要包括系统功能、系统运行环境(软、硬件)、系统安装等内容。 使用说明:系统操作使用说明较为详细地说明了操作的目的、过程、方式、输入输出的数据等。最好将系统操作的界面图放入说明书,便于使用者学习与操
16、作。 问题解释:解释了系统使用中可能出现的问题及解决办法,如非常规操作命令、系统恢复过程及意外情况与开发单位的联系方式等。 信息系统运行过程中,用户还需要记录运行日志。在发现需要对系统修正、更改的问题时,应将存在的问题、修改的考虑以及修改的影响估计作详细的描述,写成维护修改建议书(或叫维护修改申请书),提交审批。维护修改建议书也是系统运行维护期间的重要文档。,(9)系统评价报告 系统评价报告主要是根据系统可行性研究报告、系统分析说明书、系统设计说明书所确定的新系统的目标、功能、性能、计划执行情况及新系统实现后的经济效益和社会效益等给予评价。如果该信息系统的开发已作为立项的科研项目,那么,还要请
17、专家进行鉴定。系统评价报告主要包括: 概述。 系统构成。 系统达到设计目标的情况。 系统的可靠性、安全性、保密性、可维护性等状况。 系统的经济效益与社会效益的评价。 总结性评价。 有的项目聘请了相应的监理方与审计机构,那么还需要有相应的系统监理报告和系统审计报告,这两种报告的内容大体与系统评价报告相同。,(10)系统开发月报与系统开发总结报告 信息系统项目的建设开始以后,各任务的负责人应该按月向管理部门提交相应的项目进展情况报告。报告应包括进度计划与实际执行情况的比较、阶段成果、遇到的问题和解决的办法以及下个月的打算等。在整个信息系统项目开发已经完成,并且系统正式运行一段时间以后,系统开发人员
18、应与项目实施计划对照、总结实际执行的情况,如进度、成果、资源利用、成本和投入的人力,从而对开发工作做出评价,总结出经验和教训,形成系统开发总结报告。系统开发总结报告包括以下内容: 概述:包括信息系统的提出者、开发者、用户;系统开发的主要依据:系统开发的目的:系统开发的可行性分析等。 信息系统项目的完成情况:包括系统构成与主要功能;系统性能与技术指标:计划与实际进度对比:费用预算与实际费用的对比等。 系统评价:系统的主要特点;采用的技术方法与评价;系统工作效率与质量;存在的问题与原因:用户的评价与反馈意见。 经验与教训:系统开发过程中的经验与教训:对今后工作的建议:对外发表的论文。,总而言之,信
19、息系统的文档是系统建设中的重要组成部分,对于系统开发的成功和系统维护的正常起着保证和支持作用。对各阶段产生的文档要参照国家软件开发规范进行填写并按照统一的格式进行编号(本章附录中详细介绍了国家标准计算机软件产品开发文件编制指南)。文档的多少和大小、复杂程度与所开发的信息系统的大小和复杂程度成正比。另外,信息系统的文档还因开发方法的不同而有所差异。用户可根据实际情况确定信息系统开发的文档种类和内容。文档要尽可能地简单明了,便于阅读,并且尽量使用图、表进行说明。,2、系统分析说明书编写指南,系统分析说明书内容:引言项目概述实施总计划,引言,(1)摘要:摘要说明所建议开发的系统的名称、目标和功能。(
20、2)背景。项目的承担者。用户。本系统和其他系统或机构的关系和联系。(3)参考和引用资料。 本项目经核准的计划任务书或合同及上级机关的批文。 属于本项目的其他已发表的文件。本文件中各处引用的文件资料:列出文件资料的标题、编号、发表日期和制定单位。说明这些文件资料的来源。()专门术语定义:列出本文件所用到的术语。,项目概述,(1)项目的主要工作内容。 简要地说明本项目在开发中须进行的各项主要工作。这些工作是建立新系统逻辑模型的必要条件。而逻辑模型是书写系统说明书的基础。(2)系统需求说明。 新系统是在现行系统的基础上建立起来的。在新系统设计工作开展之前,必须对系统调查清楚,掌握现行系统的真实情况,
21、了解用户的新要求和问题所在。现行系统的现状调查说明:列出现行系统的目标、主要功能、用户要求等,并简要指出问题所在。业务流程说明:简要说明现行系统现场工作流程和事务流程概况。若需要反映这些业务流程的业务流程图,可以另附。,(3)系统功能说明。 在现行系统现状调查的基础上,进一步透过具体工作,分析组织内的信息、数据流动的路径和过程,真正弄清用户要解决什么问题,明确系统的功能要求。 数据流程图是系统需求的高度概括,是调查研究的重要产物。它源于现行系统,又高于现行系统。这里主要通过数据流程图概况说明系统的功能要求。 新系统的目标:从新系统数据流程图的分析中,说明新系统有哪些目标。 新系统的功能要求:列
22、出系统的主要功能。 验收:简单说明验收要求。,(4)系统的数据要求说明。 从数据流程图和数据字典分析逻辑数据结构,标识每个数据结构中的每个数据项、记录和文件的长度以及它们之间的关系。 系统的数据要求:这里的数据是指静态数据,即在运行过程中主要作为参考的数据,它们在很长一段时间内不会变化,一般不随运行而改变。 A数据项定义:说明数据项定义中出现的例外情况,列出作为控制或参考的主要数据项。 B容量:本系统所有数据项的总长度。 C用户。 D验收:指出验收情况。 系统的数据要求的粗略估计:粗略估算系统在运行过程中动态数据的内容。,实施总计划,(1)工作任务的分解。 对于项目开发中应完成的各项工作,按系
23、统功能(或子系统)划分,指定专人(或小组)分工完成,指明每项任务的负责人。(2)进度。 给出每项工作任务的预定开始日期和完成日期,规定各项工作任务完成的先后顺序以及每项工作任务完成的界面。(3)预算。 逐项列出本开发项目所需要的劳务(包括工作量/人)以及经费的预算(包括办公费、差旅费、资料费等)。,3、系统设计说明书内容指南,引言(1)摘要 (2)背景 (3)工作条件/限制 (4)参考和引用资料 (5)专门术语定义,系统总体技术方案(1)模块设计。(2)代码设计。(3)输入设计。 (4)输出设计。(5)数据库设计说明。(6)模型库及方法库设计。(7)网络设计:系统的网络 结构,功能的设计。 (
24、8)安全保密设计。 (9)实施方案说明书。,(1)摘要:摘要说明所设计的系统的名称、目标和功能。 (2)背景。 项目的承担者。 用户。 本项目和其他系统或机构的关系和联系。(3)工作条件/限制:说明本项目开发中所具备的工作条件和受到的限制。 硬件/软件/运行环境方面的限制。 保密和安全的限制。 有关部门的业务人员提供确切的数据及其定义。,有关系统软件文本。 网络协议标准文本。 国家安全保密条例。 (4)参考和引用资料 本项目的已核准的计划任务书或合同和上级机关的批文。 属于本项目的其他已发表的文件。 本文件中引用的文件资料:列出文件资料的标题、编号、发表日期和制定单位。说明这些文件资料的来源。
25、 (5)专门术语定义:列出本文件所用到的术语。,引言,系统总体设计方案,(1)模块设计。 模块设计阶段中,在系统内部划分成各个基础部分模块结构,确定系统的总体结构。总体结构与各个分层模块结构的关系是程序实施的重要依据。模块结构采用模块结构图来表示。模块结构是采用HIPO图(即分层加输入一处理一输出图)形式绘制而成的框图。 名称:列出系统中各主要功能的结构图名称和它们之间的关系。 功能:用文字简单说明主要模块结构图应具有的功能。 功能说明:说明是用伪码形式还是用结构英语形式,或者其他自然语言形式描述模块结构图的。 评价 验收:指设计人员验收的决定和处理情况。,(2)代码设计。 代码设计是信息系统
26、所必需的前提条件,是不可缺少的重要的内容。它是进行信息分类、校对、总计和检查的关键,它也用于指定数据的处理方法,区别数据类型,并指定计算机处理的内容。 代码的方式和种类:简单说明代码的方式和种类。 功能:从编码的原则要求(如单义性、可读性等)去简单说明代码所体现的功能。 评价:从识别信息、信息标准化、节省存储单元、提高运算速度、节省计算机的处理费用以及代码的特性进行评价。 验收。,系统总体设计方案,(3)输入设计。 输入设计担负着将系统外的数据以一定的格式送入计算机的任务,它直接影响到人工系统和机器系统的工作质量。输入设计的基点是确保向信息系统提供正确的信息。输入必须有必要的介质和设备。 输入
27、项目:说明对本系统的主要输入项目。 输入的承担者:说明对数据输入工作的承担者的安排,并指出操作人员、维护 人员的教育水平和技术专长。如果输入数据同某一接口软件有关,应说明该接口软件的来源。 主要功能要求:从满足正确、迅速、简单、经济、方便使用者方面的要求去说明。 输入要求:简单说明各主要输入数据类型和来源及所用的设备、介质、格式、数值、范围、精度等。 输入校验:简述所用的数据校验法和效果。 评价。 验收。,系统总体设计方案,(4)输出设计。 输出的含义是把由计算机对输入的原始数据进行处理加工的结果按一定的格式提供给用户。输出不仅有一定的格式要求,而且还必须有必要的介质和设备。 输出项目:说明对
28、本系统的主要输出项目。 输出接受者:说明输出的主要项目的数据的接受者。 主要功能。 输出要求:说明输出数据类型及所用的设备介质、格式、数值范围、精度等。 评价。 验收。,系统总体设计方案,(5)数据库设计说明。 数据库设计是指数据库应用系统的设计。编制数据库设计说明书的目的是对设计中的数据结构的所有标识、逻辑结构和物理结构做出其体的设计规定。编写提纲和内容要求如下。 概述。 A目标:说明开发的意图、应用目标、作用范围以及有关数据库开发的背景材料。 B主要功能:简要说明数据库系统的主要功能。 C用户的安排:指最终用户。说明操作人员、数据管理人员、维护人员的水平。 需求规定。 A精度:简述对数据精
29、度的要求。 B有效性:说明对数据库存取数据的有效性的要求。 C时间要求:如响应时间、数据的转换和传送时间等。 D其他专门要求。,运行环境要求。 A设备:简述运行数据库系统的硬设备及其专门功能。 B支撑软件:列出支撑软件并说明测试用的软件。 C安全保密:说明在安全保密方面的全部要求。 D其他要求。 设计考虑。 A逻辑结构设计:简要说明本系统(或子系统)内所使用的数据结构中,有关数据项、记录、文件的标识、定义、长度及它们之间存在的相互关系。 B物理结构设计:简要说明本系统内所使用的数据结构中有关数据库的存储要求、访问方法、存取单位、存取的物理关系(索引、设备、存储区域)、设计考虑和保密处理。 评价
30、:简要说明对时间、空间效率、维护代价和各种用户要求进行权衡所产生的方案性能情况。 验收。,(6)模型库及方法库设计。(7)网络设计:系统的网络结构,功能的 设计。 (8)安全保密设计。 (9)实施方案说明书。 系统总体结构设计完成以后就要确定系统实施方案,书写实施方案说明书。信息系统的研制工作就从系统设计阶段转入实施阶段。实施方案说明书就作为系统实施阶段的依据和出发点。,实施方案说明。 A项目的说明:指对系统名称、子系统名称、程序名称、程序语言、使用的设备等逐项说明。 B数据项目的说明:指对数据长度、文件名称和形式编号、构成记录的各项目名称和内容等逐项说明。 C处理内容说明:指对进行程序设计的
31、处理内容进行详细说明。实施方案的审批。 A参与审议人员:除用户、系统研制人员、程序员、操作员等以外,还包括邀请的专家、管理人员等。 B审批的实施方案:说明经审批的实施方案的概况和审批人员名单。,实施的总计划。 A工作任务的分解:对项目开发中须完成的各项工作。包括文件编制、审批、打印、用户培训工作、使用设备的安排工作等,按层次进行分解,指明每项任务的要求。 B进度:给出每项工作任务(包括文件编制)的预定开始日期和完成日期,规定各项工作任务完成的先后顺序以及每项工作任务完成的标志。 C预算:逐项列出本开发项目所需要的劳务(包括办公费、差旅费、机时费、资料费、通信设备和专用设备的租金。,三、信息系统
32、文档的编制与管理,影响文档质量的原因有上一节讲到的是否规范的问题,有认识上的问题,编写技术上的问题,评价标准的问题。而上述问题的解决都离不开对信息系统文档的管理。因而,这一节首先介绍信息系统文档编制的要求与方法,然后介绍信息系统文档的管理问题。本节内容:l、信息系统文档编制的要求与方法2、信息系统文档的管理,为了使信息系统的文档能起到前面所提到的多种沟通作用,使它有助于程序员编制程序,有助于管理人员监督和管理软件开发,有助于用户了解信息系统的工作方式和应做的操作,有助于维护人员进行有效的修改和扩充,就必然要求文档的编制要保证一定的质量。质量差的文档不仅使读者难于理解,给使用者造成许多不便,而且
33、会削弱对信息系统的管理(管理人员难以确认和评价开发工作的进展),增加信息系统的开发成本(一些工作可能被迫返工),甚至造成更加有害的后果(如误操作等)。,、信息系统文档编制的要求与方法,造成信息系统文档质量不高的原因主要有四个: (1)认识上的问题:不重视文档编写工作。 (2)规范上的问题:不按各类文档的规范写作,文档的编写具有很大的随意性。 (3)技术上的问题:缺乏编写文档的实践经验,对文档编写工作的安排不恰当。 (4)评价上的问题:缺乏评价文档质量的标准。,首先是认识上的问题。信息系统建设过程在很火程度上是应用软件的开发过程。就软件的两大部分程序和文档而言,程序相对来说是“硬件”,是必须最终
34、完成的。作为开发者往往认为只要最终程序正确,能够满足系统需求就达到了系统要求。而文档是“软件”,有一些是必须完成,而有些则无严格要求,并且也可以事后补充。因而,为了追求开发进度,一些文档资料常常被忽略。另外,文档经常是给别人看的,文档的作用很多是在事后才能体现出来的,使得系统开发人员缺乏书写文档的动力和自觉性。于是在程序工作完成以后,不得不应付一下,把要求提供的文档赶写出来。这样的做法不可能得到高质量的文档。,实际上,要得到真正高质量的文档并不容易。除去应在认识上对文档工作给予足够的重视外,还要将上节以及附录作为撰写文档时的参考,从而规范文档的写作。高质量的文档一般都需要经过编写初稿、听取意见
35、进行修改、甚至要经过重新改写的过程。高质量的文档应当体现在以下一些方面:(1)针对性 (2)精确性与统一性 (3)清晰性 (4)完整性 (5)灵活性 (6)可追溯性 (7)易检索性,为了得到高质量的文档,除认识上予以重视,采用一定的格式外,文档的编写技术非常重要。,编写原则 (1)立足于读者。(2)立足于实际需要。(3)文字准确、简单 明了。,编排原则 (1)所有文档都应该编排得便于迅速查到所需要的内容。(2)采用由一般到具体的层次结构法。(3)可能的情况下还可以采用词汇之间的互相链接。(4)在可能的情况下,应使图表放在它所解释的文字附近,以便在阅读正文的同时也能看剑图表。(5)适当使川不同的
36、字体和版式,以增加一段正文的明晰度。,装订原则 (1)如果文档需要修改,宜采用活页装订,以便可以随时去掉某页面。发行时应采用使各页面易于分开的装订方法。 (2)页面编号中间由横线连接的三组数字组成:第一组数字指卷次,第二组数字指卷内的章次,第二组数字指该章中的页次。 (3)在修改文档页码时,要加页码的第一部分与前一页的页码相同,第二部分用一个小数点后跟页号组成。例如要往429页和430页之间插入一页,那么其编号应为429.1。,词汇与索引 (1)技术术语的使用应该适当控制。 (2)使用技术术语前,要准确定义每个术语,使用也要恰如其分。 (3)不同地方对同一内容应采用同一术语。 (4)避免滥用术
37、语。 (5)每种用户文档均应有一个词汇表和索引。索引可以与词汇表结合起来。 (6)词汇表与索引的编排必须重视如何让读者快速查到该功能。,、信息系统文档的管理,信息系统的文档与其他类型的文档一样,也具有它自身的生命周期。生命周期的划分:创建期、处理期、存储期、使用期、销毁期。每种文档都处于生命周期中的某一时期。当然周期的划分也不是绝对的,各周期有时是不能截然分开的。 要强调的是,由于在整个信息系统的生存期中,各种文档作为半成品或是最终成品,会不断地生成、修改或补充。同时,这些信息系统的文档还会成为新一代系统研制时的参考和依据。因而,信息系统文档的生命周期普遍要比信息系统的生命周期长。也就是说,绝
38、大多数信息系统的文档要在相应的信息系统淘汰3至5年后才能销毁。,为了最终得到高质量的信息系统文档,达到上节提出的质量要求,在信息系统的建设过程中必须加强对文档的管理。文档管理应从以下几个方面着手进行。,(1)文档管理的制度化(2)文档要标准化、规范化(3)文档管理的人员保证(4)维护文档的一致性 (5)维持文档的可追踪性,(1)文档管理的制度化 必须形成一整套的文档管理制度,其内容可以包含文档的标准、修改文档和出版文档的条件、开发人员在系统建设不同时期就其文档建立工作应承担的责任和任务。根据这一套完善的制度来最终协调、控制系统开发工作,并以此对每一个开发成员的工作进行评价。,(2)文档要标准化
39、、规范化在系统开发前必须首先选择或制定文档标准。在统一标准制约下,开发人员负责建立所承担任务的文档资料。对于已有参考格式和内容的文档。如上节中提到的系统分析说明书,应尽量按相应的规范撰写文档。对于没有参考格式的文档。如需变更申请书,应该在项目组内部出台相应的规范和格式。表8-1是某个项目组制定的内部使用的需求变更申请书格式。,(3)文档管理的人员保证 项目小组应设文档组或至少一位文档保管人员,负责集中保管本项目已有文档的两套主文本。两套文本内容应完全一致。其中的一套可按一定手续,办理借阅。,()维持文档的可追踪性 由于信息系统开发的动态性,系统的某种修改是否最终有效,要经过一段时间的检验,因此
40、文档要分版本来实现。而各版本的出版时机及要求也要有相应的制度。,(4)维护文档的一致性 信息系统开发建设过程是一个不断变化的动态过程,一旦需要对某一文档进行修改时,要及时、准确地修改与之相关联的文档:否则将会引起系统开发工作的混乱。而这一过程又必须有相应的制度来保证。,项目成员可根据工作需要在自己手中保存一些个人文档。项目开发结束时,文档管理人员应收回开发人员的个人文档。发现个人文档与主文有差别时,应立即着手解决。这常常是未及时修订主文本造成的。,往新文档取代了旧文档时,文档管理人员应及时注销旧文档。主文本的修改必须特别谨慎。修改以前要充分估计修改可能带来的影响,并且要按照:提议、评议、审核、
41、批准和实施等步骤加以严格控制。,以上是系统建设过程中文档管理需注意的问题,至于运行过程中的文档管理,与开发过程中的文档管理的方法大同小异,这里就不再赘述。 撰写文档的目的是为了指导信息系统的开发、维护和帮助用户的使用。前面讲到的都是如何提高文档本身的质量。下面要讲到的是文档的使用者如何快速地从文档中得到所需的内容。所以文档管理的另一个重要问题是:如何在需要的时候,将它们迅速、准确、全面地检索出来。,信息系统的文档大部分都是在计算机上完成的,基本具备电子文档的性质。但是要将这些电子文档实现快速检索就不仅仅是建几个子目录、建几层子目录的问题了。这涉及到与待建项目相对应的文档管理信息系统的建立。 应
42、该说明的是,这里对信息系统文档的检索管理经常涉及的对象并不是档案全文,而是对档案原文进行加工、处理后得到的档案二次文献信息,即其中具有特定标识意义的部分,如文档名、责任者、关键词等项目。当然记录中的项目可以根据实际情况增加或减少。,这样,通过适当的数据结构,使文档按内容分类,建立相应的文档管理信息系统就能做到对信息系统的文档作快速的检索了。 在文档管理信息系统中,还可设置一些检索的约束。我们可以把它们视作两个条件:前置条件和后置条件。前置条件意味着在使用该文档之前要首先检验的条件。例如,阅读文档的用户级别:只允许项目经理查阅的文档,不是经理就不能访问该文档。后置条件意味着将该文档归档之前必须满
43、足的条件,比如必须填写的文档项,如负责人的签字。,从上述文档管理的内容可以看出,如果采用手工方式建立这些文档资料,很难适应这种不断修改、不断完善的客观需求。因此,信息系统文档的建立应当充分利用现有的辅助开发工具及一些字处理软件等。目前已经有相应的CASE工具能够自动生成信息系统的某些文档。有些工具还能辅助进行文档的检索管理。这些工具的使用能够有利于提高信息系统文档的质量,从而最终提高信息系统的开发质量和运行质量。,l、详细说明信息系统文档的作用。2、信息系统的文档有哪几种分类方法,各有哪些类型?3、讨论不同的开发方法在编写文档时的区别。4、你认为对于小型的信息系统应该撰写哪些文档?5、文档在信息系统开发中没有受到足够重视的原因是什么?你有什么好办法激励开发人员写好文档?6、高质量的文档应该包含哪些内容?如何编写高质量的文档?7、信息系统文档的管理应从哪几方面着手? 8、请你设计信息系统文档检索信息系统的功能。9、有兴趣的同学可以试着开发一个文档管理信息系统。,思考题,