第四讲软件文档表达诗歌是思想的疑聚，廖廖几行诗句能表极为复杂的思想。软件文档如何表达？34涉众文档涉众通常是系统文档或系统的既得利益者。要有一个基本规则，把良好的、可用的文档，与那些拙劣的、缺乏考虑的文档区分开来。即所谓合理文档的规则，共有7条：1.从读者的角度编写文档2.避免出现不必要的重复3.避免歧义4.使用标准结构5.记录基本原理6.使文档保持更新，但频度不要过高7.针对目标的适宜性对文档进行评审这是一个区分良好的、可用的文档和有欠缺的、甚至是拙劣的文档的规则。规则1：从读者的角度编写文档这是一个浅显、重要，但总是被忽略的规则。然而，遵守该规则，会给你带来以下优势：面向读者编写的文档，通常总会赢得读者。面向读者编写文档是一种礼貌的表现。避免使用令人生厌的专业术语。容易使文档变得易读、易理解，提高文档的“效率”。对于专业读者，好的文档将有利于系统设计思想、代码等的理解。文档编制者在编写文档时，通常会采用两种形式：意识流或执行流。意识流：按思维在编写者头脑中出现的顺序捕捉思维，并加以记录。通常缺乏可读的组织结构。执行流：按软件执行时的思维顺序捕捉思维，并加以记录。编制文档时，首先应该明确文档的每一节将要回答(或说明/记录)什么问题，并对自己的文档进行有效的组织。规则2：避免出现不必要的重复要点：将每个信息都记录在确切的地方。如此，可使文档更便于理解和使用，在需要演化时，也能更便于修改。同时，这一方法还能避免产生混乱。有时，重复信息的细微差别会使读者心生疑问，影响文档的可理解性。但是，“避免不必要的重复”并不是机械的，必须墨守的成规。下列情况下，有时还是可以有必要的信息重复：1.如果，过多的不必要的翻页，可能会使读者生厌。因此，信息引用的位置非常重要。2.有时，为了使表达更为明确，或者在表达两个不同观点时，两个不同的视图可能会包含重复的信息。3.还有，就是为了保持文档的独立和自成体系，需要在同一文档体系的不同文档之间的各文档保留一定的重复信息。“避免不必要的重复”只是一个规则而已，而规则本身不能影响读者的理解。所以，有时以不同的形式表达相同的思想，只是为了有助于读者更透彻的理解，而不是对规则的违反。规则3：避免歧义要点：采用语义精确、定义明确的表示法。通常，只要采用一组事先约定的表达，然后尽可能避免出现意外重复，尤其是那些仅有“细微差别”的重复，就能有助于消除或避免歧义。但是，形式语言并不是始终或总是需要的，因为还必须兼顾文档的可读性、可理解性和可修改性。应该尽量使文档读者确定或便于确定表示法的含义，除非双方默契。特别是文档编制者引用其他地方定义的语义源，即使这个语义源是标准的或广泛应用的语言，由于可能存在不同的版本，也应该使读者明确引用的具体版本。如果这样引用的一种表示法是用于内部开发的，就应该将其添加到内部技术文档编制所采用的符号体系中去。上述关于表示法引用的阐述，是避免歧义的一个良好的习惯。这样，既能迫使你对系统各部分及其之间的关系加以了解，并能更为精准的表述。规则4：使用标准结构要点：标准结构有利于文档被更好的阅读和利用。应该有计划的制定文档的标准结构方案，并确保文档的编制过程能够遵守，确保读者能够了解、理解。标准结构文档至少具备以下优点：能够帮助读者在文档中导航和快速查询特定信息。能够帮助文档编写者计划和组织内容，并透露那些带有“待定”标签的节，还有什么工作等待完成。可以方便表达文档各节需要表达的重要特征集，这样可以体现信息完整性规则。具有标准结构的文档，其标准结构的另一个重要用途就是，能组成评审时文档验证的基础。规则5：记录基本原理要点：对基本原理进行记录可以节约大量的时间。在编制决策结果的文档时，应该对被放弃的方案进行记录，并说明放弃的原因和理由。这样的记录，或者是将来接受详细检查或被迫更改的需要，或者是为了以后可以重用设计。通常在以下情况需要记录基本原理：在做出决策前，设计团队必须花费大量时间评估各种候选方案；决策对于某一需求或目标的实现很重要；初看似乎决策意义不明，但细察其背景信息后，决策变得逐渐明朗；在若干场合，有人向你提问：为什么这样做？为团队新成员解惑；决策具有广泛影响，也难以消除这种影响；你认为，现在捕捉基本原理，比以后捕捉更加经济划算。规则6：使文档保持更新，但频度不要过高要点：人们总是乐意使用保持更新、内容精准的文档。软件文档应该是该软件最终、最权威的信息源。通过引用合适的文档，我们能够最为容易、最为有效地回答关于该软件的问题。然而，文档的更新却没有必要为那些无法持久的决策做出反映。这样做，其实是一种高成本和浪费资源的愚笨做法。事实上，应该在开发计划中指定文档更新的特定内容或过程，使文档服从版本控制，并制定一项文档发布策