敏捷环境下如何写文档之反模式 | 论只写有用的文档

简单说就一句话，敏捷文档的特点是易于使用且易于更新。 

精简文档的目的是帮助你（作为读者）找到问题的答案，而不是自己掌握详细的答案。涉及到IT系统和代码的文档时，尤其如此。代码本身应该是该问题的最好答案。文档应仅帮助指引寻找答案的方向。 

打个比方，一本书的内容好比是代码，好的文档就是这本书的目录，而不是本书的摘要。目录非常简短且易于阅读，并且更新频率很低。目录通常是分层的（比如部分、章节、小节），这样查看会更快。

接下来我们看一些文档的反模式。

反模式＃1 – 没有文档

在许多组织中，没有文档是最常见的反模式。经常发生这种情况是因为他们没有阅读或错误解读了”敏捷宣言 ”的一部分， 其中说：”尽管右项有其价值。” 

“无文档”的相近模式是”随心所欲的文档”模式。我们还是用书的类比，没有任何文档说明你需要阅读和记住整本书（因为没有目录），才能知道在哪里能找到问题的答案。这种反模式的后果是人们需要花费很长的时间才能进入工作。这会导致信息孤岛、组件团队、局部优化、扩展困难等问题。

反模式2 – 过于详细文档

为了克服反模式＃1，一些组织认为，详细的文档就是答案。还是用书的类比，这就像写本书的摘要。问题是随着书的内容不断更新，要保持摘要更新需要大量的工作。而且一旦不更新，就无法再使用了。这意味着情况与反模式1相同。

反模式3 – 需求作为文档

这是一种奇怪的文档类型，但是某些组织将有关功能需求的详细信息保存成文档。问题在于这些需求只是增量，即系统中一个状态与下一状态之间的差异。要了解当前状态，你需要构建全部。如果这些增量中有丢失，则说明文档（需求文档）不受信任。这可能比没有文档更糟糕，因为这只会使读者感到困惑。