无处不再的重构－文档重构
我们需要什么样的文档
大家对文档常见的两种抱怨：
1. 项目没有文档，一团糟，接手后不知从哪里下手。
2. 文档太多，每天都有一堆的文档要看，要写，还要维护文档间的相互关系，引用。
抱怨归抱怨，但是我们都知道，一个项目没有文档是不行的，文档太多也是万万不行的。有时候错误的，一团糟的文档比没有文档更可恶。那么我们想要什么样的文档呢？当然是好的文档，对与什么是坏的，我们可以很容易地下一个定义，但是对于什么是好的，常常是有那么一些想法，却不怎么具体，所以从什么是不好的文档开始可能更容易些，不好的文档存在的问题通常是：
1. 没有层次。没有自顶向下的文档结构和大纲，显得没有条理。
2. 没有目录结构，没有其他文件的引用，要找个东西得从头开始。
3. 多个文档中对同一问题重复说明，要是文档间一致的话还好，要是不一致就会造成误导。
4. 文不对题。文档内容中描述的问题和文件名或章节名称不搭界。
5. 用词不准确。例如给用户看的文档中出现客户所不熟悉的计算机术语。在设计文档中又出现一些业务用语。
6. 目录引用，链接失效。在经过一些变更后文档中的链接，目录可能失效，导致无法跳转到指定的内容。
7. 对于变更没有记录，不能有效区分变更的内容。
8. 对问题描述模糊不清。语言组织不好，流程描述不清晰。
9. 图片太多或太少。有时图片可以帮助理解，但是有时文字比图片更能说明问题。
10. 多个文档在一起没有统一的规划，组织。
现在把上面的十条都反过来，就是好的文档的特点了。看来要写出好的文档真不容易，所以，一方面，文档的阅读者想看到好的文档，另一方面，文档的写作比起写代码来是很枯燥的，同时没有很好的工具的支持，造成要写出好的文档是需要下大功夫的。
文档也是会腐化的
文档写出来就是要给人看的，所以写文档前首先要确定这个文档给谁看，他想从文档中获取哪些信息。在这里我们把文档分为两类，一类是给客户看的，一类是给开发者看的。
给客户看的主要是需求和软件的使用手册，软件的帮助。
给开发者看的主要是各类设计，测试文档，还有相关业务的说明（业务名词的解释等）。
对这两种文档，随着软件开发过程的迭代进行，随着需求的变化，都会作相应的修改，否则文档就失去了意义。但是现实中，我们完全有借口去推掉这份出力不讨好的工作。例如工期太紧，人手不够等等。也就是说，随着开发的进行，之前很清晰，很准确的文档渐渐变的不合时宜，变的错误，变成了误导人的谎言。所以，文档也在慢慢腐化，这一点，和代码的腐化是有相似性的。
文档和重构
在应对代码腐化上，有重构。在应对文档的腐化的时候，我们也可以借用重构的思想。
其实，我们可以把上面提到的10个坏文档的特征和重构中代码的坏味道（Bad Smell）的概念对应起来。当我们的文档表现出这些特征时，我们应该整理相关的内容，进行重构。
在这里，代码重构的一些常用手法也可以派上用场。举几个例子：
l 当我们发现文档出现上面的第4条的坏味道“文不对题。文档内容中描述的问题和文件名或章节名称不搭界”或者第5条“用词不准确。例如给用户看的文档中出现客户所不熟悉的计算机术语。在设计文档中又出现一些业务用语”的时候。可以使用RenameMethod，把对应的目录或者文件改名，来清楚的表明你的文档中都包含什么内容。如果你修改了文件名，你就需要查找其他文档中用到的地方，进行全部替换。将不太专业的用语替换成专业名词，提高表述的准确度。
l 当文档中出现第8条的坏味道“对问题描述模糊不清。语言组织不好，流程描述不清晰。”时。我们可以使用ExtractMethod，因为出现这种情况大多是由于想表述的东西太多，造成条理不清。所以将要说的内容分成多个单独的条目会比较有帮助。
当出现第3条“多个文档中对同一问题重复说明”时，也可以使用ExtractMethod，来把对问题的描述放到真正适合它的地方。
l 当出现第1条和第2条的坏味道时，我们需要整理一组文档的结构，使其按照对问题描述的不同层面来划分。实现一个由粗到细的结构。这样就可以把每个文档纳入这个体系，并且建立完整的引用关系。
何时对文档重构
在这一点上，何时对代码进行重构的观点在这里也是适用的。
当你发现一个文档表现出不好的特征时，就应该对它进行整理，重构，让它适应当前的情况。 因为不管文档是给用户看的还是给开发者看，都有根本的一点，这些文档的写作都不是一蹴而就的。而且一般项目的压力也不允许你腾出专门的时间来写文档，倒是经常在项目交付之后再回头恶补。而更多的是随着开发一点一点积累起来的，随着需求，设计，编码，测试所有的这些过程不断变化的。
如果你还不能作到随时进行文档的重构，那么项目在达到一个里程碑之后的短暂休整时间是作这件事的好时机。这个时间段里，较多的是确认，反馈，少了加班赶进度的情况，因此应该是有精力来作的。再者，有没有变更在这段时间都会确定下来。
最后的话
这段时间作维护项目，看了，写了一些文档，小有感触，于是写了这些。把文档和重构扯上关系似乎有点牵强，虽然重构的手法不是都能用的上，我们也没有什么专门的文档重构的手段，更没有《重构》这本书里的70几个重构手法，但是作为重构的思想可以运用到文档的写作上，并且相信能够帮助改善文档的质量。
