设计文档编写的建议（智力拼图的叫法很有意思！）

1，防止编写成智力拼图
许多文档写成了类似智力拼图的玩具，很多不同的相关定义与内容散落在文档的不同地
方。读者不会预料到在文档的其它地方会不会还有相关说明。为了阅读这样的文档，人们需
要把一切都记在脑子里，智力拼图是把散落在各处的小块拼在一起，但人的大脑很难做到这
一点。
要记住，任何大的文档都不同程度的具有智力拼图性质，但我们的任务是减少智力拼图
块的数量。不要让阅读者在一个地方看到的信息块做出了推论，而在另一个地方才发现这个
理解是错误的，这就很危险。
组织文档的原则，大多数情况下是防止出现智力拼图的情况，如果需要，可以把文档中
对某个名称的定义和描述都找出来，统一放在某个固定的、唯一的位置上，必要的时候还可
以建立术语表。如果无法将相关信息都集中在一个章节，就需要增加引用页面，这样读者就
不会迷惑了。
我们这个课程讲义的编写本身就是一个文档化过程，除了定义清楚问题域以外，整个课
程的思考方式是基于问题、研究对策、寻找解决方案，而不是依据于某个人说过什么，某个
标准是什么（何况标准也是在变化的）。在书写方式上，以读者为中心，力求通俗易懂、内
容连贯、条理清楚。在内容组织上，力图减少不必要的拼图游戏，减少不必要的前后查阅。
相似的概念和名词，只要在各个章节中，都力图自成逻辑体系，使得读起来省力清晰。
这些特征，在文档的编写中都是需要注意的。
2，防止编写成鸭叫文档
有些文档编写出来为什么相关人员不愿意看呢？为什么自认为似乎已经描述的很清楚
的文档，在读者感觉模糊不清难以阅读呢？我们来看看下面的描述：“机票预定数据验证函
数应该验证机票预定数据”。这样的句子确实使人莫名其妙，这到底是什么意思？如何测试
它？这很容易使人联想到一种鸭叫演讲，单调、温顺、平庸、符合官方标准，但是叫人提不
起精神，看起来描述了很多，但实际上什么也没有描述。
把自己写的句子大声念出来，如果发现自己写了很多毫无疑义的句子，只是一味的迎合
标准要求，就要考虑重新框定问题，使文档写出来具有精神，读者读起来也有精神。
3，不要为了文档而文档
软件质量保证使每个开发组织都很关注的，为了保持一致的软件质量，我们需要一套独
立定义的质量准则，所以，过程的定义与文档规范就成为很多组织很关注的内容。但也会发
生文档的使用与功能正确实现无关的情况，由于文档记录要与文档标准保持一致，结果使用
起来将非常繁琐而散乱。
这种书写文档的理念只是为了应付检查，而不是促进效率与更好的开发，是为了文档的
本身，是为了文档而文档的书写方式。书写这种文档的目的只有一个，那就是证明我们正在
做和官方保持一致的事情，如果有什么差错，那不是我的责任。至于项目能不能完成，那不
是我考虑的问题。
很多文档都没有被任何人阅读，其原因是人们无法理解他，不适合相关人员的习惯，也
没有办法把文档与自己的开发工作联系起来。当然，确实很多评审只关注文档格式而不是文
档有效性，只关注文档字数多少而不是内容的思想性。这种东西不是单靠开发单位能解决的，
如果这样的评审是一定存在的，那一个建议就是：开发两套文档，一套用于评审，一套用于
开发小组内部。这看起来多费了时间，但所费的时间是值得的，总比把应付评审的格式化文
档用于实际开发从效率上要高的多。试试看，就会发现这个建议的意义。
4，图与文的协调
谈到设计文档就免不了使用图形表达，不过在图和文的协调上需要下点功夫。图比较适
合说明关系，而文字比较适合表达细节。这两者是不可互相替代的。作为设计，如果没有图，
相关人员对问题域就可能不能得到一个整体的概念。但是没有详尽的文字表达就不可能定义
开发，也不可能使开发指向我们所需要的方向。图不需要面面俱到只需要表达重点需要表达
的内容，而文字的详细程度应该足以定义开发的关键点，但也要给开发人员留出适当的发挥
空间。
有的单位热衷于把类图直接生成代码，这是一个误会，也是把图用错了地方。代码是事无巨
细的，而且与编码员个人的特征有很大关系。图没有必要画得那么细，也不可能画的那么细。
画图要表现出聪明，要说明每个结构策略的原因，也要说明所采用的策略所带来的负面影响，
仅仅按照某个模式来做设计那是初学者的事情，一个高级设计人员的思维方式，是突破一切
框框，目的就是一切。