软件文档写作文档表达1优质PPT.ppt

软件文档写作文档表达1优质PPT.ppt

《软件文档写作文档表达1优质PPT.ppt》由会员分享，可在线阅读，更多相关《软件文档写作文档表达1优质PPT.ppt（17页珍藏版）》请在冰豆网上搜索。

第四章第四章软件文档表达软件文档表达14.24.2合理文档的合理文档的77条规则条规则软软件件文文档档必必须须能能服服务务于于各各种种用用途途。

比比如如，它它应应该该抽抽象象到到足足以以使使新新员员工工能能迅迅速速理理解解它它；

它它应应该该详详细细到到足足以以作作为为设设计计的的蓝蓝图图；

它它应应该该包包含含足足够够的的信信息息，以便作为分析和决策的基础。

以便作为分析和决策的基础。

软软件件文文档档可可能能既既是是指指示示性性文文档档，又又是是说说明明性性文文档档。

例例如如，对对某某些些读读者者而而言言，它它能能指指示示什什么么应应该该是是正正确确的的，并并对对决决策策的的制制定定施施加加限限制制；

对对另另一一些些读读者者而言，它能而言，它能说明说明什么是正确的，并详述已经就系统设计作出的决策。

什么是正确的，并详述已经就系统设计作出的决策。

因因此此，在在对对文文档档jj进进行行设设计计和和评评审审的的过过程程中中，必必须须确确保保它它能能支支持持所所有有相相关关的需求。

的需求。

了了解解文文档档的的用用途途是是一一件件极极为为重重要要的的事事情情，因因为为这这些些用用途途确确定定了了文文档档的的形形式。

通常，软件文档基本具有式。

通常，软件文档基本具有33种用途：

种用途：

1.1.用用作作教教育育工工具具。

包包括括向向成成员员介介绍绍系系统统。

而而成成员员可可能能是是新新的的团团队队成成员员，或或者者是外部合作开发的分析师。

是外部合作开发的分析师。

2.2.用用作作涉涉众众间间的的首首要要通通信信工工具具。

这这取取决决于于涉涉众众需需要要什什么么样样的的通通信信。

下下表表给给出出了一些相关范例。

了一些相关范例。

3.3.作作为为系系统统分分析析的的基基础础。

为为了了支支持持分分析析工工作作，相相关关文文档档必必须须包包含含执执行行特特定定分分析的必要信息。

析的必要信息。

2表表：

相关文档和涉众通信需求：

相关文档和涉众通信需求涉涉众众通通信信代表客户代表客户（群群）的需求工程师的需求工程师和系统分析师和系统分析师就各种竞争性需求进行协商和权衡的论坛就各种竞争性需求进行协商和权衡的论坛组成部分构架师和设计人员组成部分构架师和设计人员解决资源争端，并确定性能和其它运行时资源解决资源争端，并确定性能和其它运行时资源消费预算消费预算实现者实现者为下游设计活动提供不能违背的限制和可利用为下游设计活动提供不能违背的限制和可利用的特权的特权测试工程师和集成工程师测试工程师和集成工程师为必须组合在一起的部件指定正确的黑盒行为为必须组合在一起的部件指定正确的黑盒行为维护工程师维护工程师维护活动的起点，揭示预期更改会影响的区域维护活动的起点，揭示预期更改会影响的区域必须和该系统进行交互的其必须和该系统进行交互的其他系统设计师他系统设计师确定打算提供和要求的操作集，及其操作协议确定打算提供和要求的操作集，及其操作协议管理人员管理人员组成开发团队的基础，这些团队分别对应已确组成开发团队的基础，这些团队分别对应已确认的工作任务、工作故障结构、计划、项目资认的工作任务、工作故障结构、计划、项目资源分配和由各团队执行的进展跟踪源分配和由各团队执行的进展跟踪产品线管理者产品线管理者确定产品家族中潜在的新成员是否处于范围之确定产品家族中潜在的新成员是否处于范围之内，如果处于范围之内，距离多远内，如果处于范围之内，距离多远质量保证小组质量保证小组一致性检验的基础，目的是确保实现方案取得一致性检验的基础，目的是确保实现方案取得系统要求的实际成果系统要求的实际成果3文档涉众通常是系统文档或系统的既得利益者。

文档涉众通常是系统文档或系统的既得利益者。

因此，必须要有一个基本规则，把良好的、可用的文因此，必须要有一个基本规则，把良好的、可用的文档，与那些拙劣的、缺乏考虑的文档区分开来。

即所档，与那些拙劣的、缺乏考虑的文档区分开来。

即所谓谓合理文档的规则合理文档的规则，共有，共有77条：

条：

1.1.从读者的角度编写文档从读者的角度编写文档2.2.避免出现不必要的重复避免出现不必要的重复3.3.避免歧义避免歧义4.4.使用标准结构使用标准结构5.5.记录基本原理记录基本原理6.6.使文档保持更新，但频度不要过高使文档保持更新，但频度不要过高7.7.针对目标的适宜性对文档进行评审针对目标的适宜性对文档进行评审这是一个区分良好的、可用的文档和有欠缺的、这是一个区分良好的、可用的文档和有欠缺的、甚至是拙劣的文档的规则。

甚至是拙劣的文档的规则。

4规则规则11：

从读者的角度编写文档：

从读者的角度编写文档这是一个浅显、重要，但总是被忽略的规则。

然而，遵守该规则，会给这是一个浅显、重要，但总是被忽略的规则。

然而，遵守该规则，会给你带来以下优势：

你带来以下优势：

1.1.面向读者编写的文档，通常总会赢得读者。

面向读者编写的文档，通常总会赢得读者。

2.2.面向读者编写文档是一种礼貌的表现。

面向读者编写文档是一种礼貌的表现。

3.3.避免使用令人生厌的专业术语。

避免使用令人生厌的专业术语。

4.4.容易使文档变得易读、易理解，提高文档的容易使文档变得易读、易理解，提高文档的“效率效率”。

对于专业读者，。

对于专业读者，好的文档将有利于系统设计思想、代码等的理解。

好的文档将有利于系统设计思想、代码等的理解。

文档编制者在编写文档时，通常会采用两种形式：

意识流或执行流。

意识流意识流：

按思维在编写者头脑中出现的顺序捕捉思维，并加以记录。

通：

通常缺乏可读的组织结构。

常缺乏可读的组织结构。

执行流执行流：

按软件执行时的思维顺序捕捉思维，并加以记录。

：

编制文档时，首先应该明确文档的每一节将要回答编制文档时，首先应该明确文档的每一节将要回答（或说明或说明/记录记录）什么什么问题，并对自己的文档进行有效的组织。

问题，并对自己的文档进行有效的组织。

规则规则22：

避免出现不必要的重复避免出现不必要的重复要点要点：

将每个信息都记录在确切的地方。

如此，可使文档更便于理解和使用，在需要演化时，也能更便于修改。

同同时时，这这一一方方法法还还能能避避免免产产生生混混乱乱。

有有时时，重重复复信信息息的的细细微微差差别别会会使使读读者心生疑问，影响文档的可理解性。

者心生疑问，影响文档的可理解性。

但但是是，“避避免免不不必必要要的的重重复复”并并不不是是机机械械的的，必必须须墨墨守守的的成成规规。

下下列列情情况下，有时还是可以有必要的信息重复：

况下，有时还是可以有必要的信息重复：

1.1.如如果果，过过多多的的不不必必要要的的翻翻页页，可可能能会会使使读读者者生生厌厌。

因因此此，信信息息引引用的位置非常重要。

用的位置非常重要。

2.2.有有时时，为为了了使使表表达达更更为为明明确确，或或者者在在表表达达两两个个不不同同观观点点时时，两两个个不不同的视图可能会包含重复的信息。

同的视图可能会包含重复的信息。

3.3.还还有有，就就是是为为了了保保持持文文档档的的独独立立和和自自成成体体系系，需需要要在在同同一一文文档档体体系系的不同文档之间的各文档保留一定的重复信息。

的不同文档之间的各文档保留一定的重复信息。

“避避免免不不必必要要的的重重复复”只只是是一一个个规规则则而而已已，而而规规则则本本身身不不能能影影响响读读者者的的理理解解。

所所以以，有有时时以以不不同同的的形形式式表表达达相相同同的的思思想想，只只是是为为了了有有助助于于读读者者更更透彻的理解，而不是对规则的违反。

透彻的理解，而不是对规则的违反。

规则规则33：

避免歧义避免歧义要点要点：

采用语义精确、定义明确的表示法。

通通常常，只只要要采采用用一一组组事事先先约约定定的的表表达达，然然后后尽尽可可能能避避免免出出现现意意外外重重复复，尤其是那些仅有尤其是那些仅有“细微差别细微差别”的重复，就能有助于消除或避免歧义。

的重复，就能有助于消除或避免歧义。

但但是是，形形式式语语言言并并不不是是始始终终或或总总是是需需要要的的，因因为为还还必必须须兼兼顾顾文文档档的的可可读读性、可理解性和可修改性。

性、可理解性和可修改性。

应应该该尽尽量量使使文文档档读读者者确确定定或或便便于于确确定定表表示示法法的的含含义义，除除非非双双方方默默契契。

特特别别是是文文档档编编制制者者引引用用其其他他地地方方定定义义的的语语义义源源，即即使使这这个个语语义义源源是是标标准准的的或或广广泛泛应应用用的的语语言言，由由于于可可能能存存在在不不同同的的版版本本，也也应应该该使使读读者者明明确确引引用用的的具具体体版版本。

本。

如如果果这这样样引引用用的的一一种种表表示示法法是是用用于于内内部部开开发发的的，就就应应该该将将其其添添加加到到内内部部技术文档编制所采用的符号体系中去。

技术文档编制所采用的符号体系中去。

上上述述关关于于表表示示法法引引用用的的阐阐述述，是是避避免免歧歧义义的的一一个个良良好好的的习习惯惯。

这这样样，既既能能迫迫使使你你对对系系统统各各部部分分及及其其之之间间的的关关系系加加以以了了解解，并并能能更更为为精精准准的的表表述述，而而且，对读者也是一种周到的考虑和尊重。

且，对读者也是一种周到的考虑和尊重。

规则规则44：

使用标准结构使用标准结构要点要点：

标准结构有利于文档被更好的阅读和利用。

应该有计划的制定文档的标准结构方案，并确保文档的编应该有计划的制定文档的标准结构方案，并确保文档的编制过程能够遵守，确保读者能够了解、理解。

制过程能够遵守，确保读者能够了解、理解。

标准结构文档至少具备以下优点：

1.1.能够帮助读者在文档中导航和快速查询特定信息。

能够帮助读者在文档中导航和快速查询特定信息。

2.2.2.2.能够帮助文档编写者计划和组织内容，并透露那些带有能够帮助文档编写者计划和组织内容，并透露那些带有“待定待定”标签的节，还有什么工作等待完成。

标签的节，还有什么工作等待完成。

3.3.3.3.可以方便表达文档各节需要表达的重要特征集，这样可可以方便表达文档各节需要表达的重要特征集，这样可以体现信息完整性规则。

以体现信息完整性规则。

4.4.具有标准结构的文