软件文档写作07-文档写作.ppt

* 5.1 有关系统开发生命周期文档的讨论 见教材p140 第五章 软件文档写作要求 一个讨论如何编制系统开发生命周期文档的案例 系统设计生命周期文档 NetReptile推荐?[2005-4-4] 出处：zdnet 作者：不详 ? 多数押宝微软.NET技术的公司通常也会选用微软的生产性工具。只要采用正确的过程，布局和规范，公司就能结合他们的开发环境和生产性工具创建一个可用的系统设计和系统维护结构。让我们先回忆一下书写文档过程，然后再分析一下你的系统设计工具箱里应该有哪些产品和工具。 书写文档过程 即使每家公司都赞同他们应该有一个软件开发周期(SDLC)，但是没有两家公司对每个阶段以及工作产品下的定义完全一样。在创建你自己的软件设计方法以及选择实现工具的时候，你必须首先定义你的设计过程和书写文档过程。定义的一部分应该包含对每个项目创建和维护的一组文档。最起码，你应该创建下面的文档(或者其它包含所有这些部分的文档)。 商业需求 商业需求文档应该概括说明开发系统的原因，预期的系统总成本，以及实现的收益等。还应该列出预期的使用和性能量度，(例如，什么类型的用户将使用该系统，系统的响应时间等)。商业需求文档将用来指导系统设计所有的后继阶段。对该文档所做的任何改动必须反映实际的设计和开发中，而且在设计和开发之前进行核准。 过程图表(process diagram)和使用案例(use cases) 一旦定义了商业需求，系统架构师书写文档的内容就转到系统的关键参与者之间信息的流动方式上来。定义参与者和过程是创建使用案例的关键，它根据参与到这个系统的人或系统来定义每个主要的系统功能。过程图表和使用案例文档放到一起将提供连接商业需求和高层技术实现的信息。同样地，文档应该易于理解，易于客户(或者商业倡导者)编辑，易于系统架构师创建详细技术文档。 建模文档 系统架构师应该使用过程图表和使用案例模型作为源文档来创建类模型和数据库模型。类模型将系统表示为一组定义在使用案例中的，用于实现系统主要功能的逻辑类。数据库模型将提供用来存储瞬间过程状态信息、瞬间系统输出以及历史事务数据的数据库的物理实现。 书写系统文档的三个主要工具 当然，你可能永远都不会在初期得到所有的完成得很好的系统需求文档和系统设计文档。选用那些在开发过程中允许你改变设计以及公布这些改变的工具是很重要的。要获取所有用来创建设计环境的工具，你的开发人员至少应该有Microsoft Office Professional以及Microsoft Visual Studio .NET Enterprise Developer。所有系统构架师应该使用相同版本的Office，使用Microsoft Visual Studio .NET Enterprise Architect。这将为系统构架师提供一个使用Microsoft Visio for Enterprise Architects的许可。 对于你的设计环境，关键工具是Microsoft Word，Microsoft Visio以及SharePoint Team Services(STS)。Word有一些非常好的团队协作工具。工具菜单中的跟踪变化功能允许多人编辑一个文档，并将其改变记入文档。编辑者(例如商业倡导者、系统构架师或者开发人员等)可以往文档中添加注释，而不是直接改变文档。他们可以向复查人员发送文档的拷贝。之后，他们就可以根据那些注释将所有的变化合并到原始文档中，决定接受那个改变，丢弃那个改变。 Visual Studio .NET Enterprise Architect版本中的Visio的版本包含创建使用案例、类模型和数据库图表的模板。你甚至可以使用类模型产生函数模板，使用数据库图表工具产生SQL Server以及其它的兼容ODBC的数据库的数据库模式。事实上，对于在目前在用的系统来说，你可以反向地从VB代码得出类模型，从数据库得出数据库图表。Visio不像Word一样能跟踪多个用户对文档的改变，但是它却可以得到设计的反馈信息，这一点是很重要的。为了允许在类模型和数据库图表上做注释，我推荐系统架构师将它们的模型和图表做成JPEG文件贴到一个Word文档中。这样你不仅可以打印、查看图表，也可以使用Word的跟踪改变的特性。 一旦创建了文档之后，将它们放到多个用户可以查看并对其注释的地方。在Office2000、Office XP以及Microsoft FrontPage 2000或者更高版本的每个拷贝中都带有一个简单协作服务器。这个工具，即STS，可以用来创建一个基于Web的入口(portal)，作为关键设计文档的一个仓库。 STS使用Web浏览器或者Wo