敏捷反模式

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

Bob Jiang
简单说就一句话,敏捷文档的特点是易于使用且易于更新。 精简文档的目的是帮助你(作为读者)找到问题的答案,而不是自己掌握详细的答案。涉及到IT系统和代码的文档时,尤其如此。代码本身应该是该问题的最好答案。文档应仅帮助指引寻找答案的方向。 打个比方,一本书的内容好比是代码,好的文档就是这本书的目录,而不是本书的摘要。目录非常简短且易于阅读,并且更新频率很低。目录通常是分层的(比如部分、章节、小节),这样查看会更快。 接下来我们看一些文档的反模式。 反模式#1 – 没有文档 在许多组织中,没有文档是最常见的反模式。经常发生这种情况是因为他们没有阅读或错误解读了”敏捷宣言 ”的一部分, 其中说:”尽管右项有其价值。” “无文档”的相近模式是”随心所欲的文档”模式。我们还是用书的类比,没有任何文档说明你需要阅读和记住整本书(因为没有目录),才能知道在哪里能找到问题的答案。这种反模式的后果是人们需要花费很长的时间才能进入工作。这会导致信息孤岛、组件团队、局部优化、扩展困难等问题。 反模式2 – 过于详细文档 为了克服反模式#1,一些组织认为,详细的文档就是答案。还是用书的类比,这就像写本书的摘要。问题是随着书的内容不断更新,要保持摘要更新需要大量的工作。而且一旦不更新,就无法再使用了。这意味着情况与反模式1相同。 反模式3 – 需求作为文档 这是一种奇怪的文档类型,但是某些组织将有关功能需求的详细信息保存成文档。问题在于这些需求只是增量,即系统中一个状态与下一状态之间的差异。要了解当前状态,你需要构建全部。如果这些增量中有丢失,则说明文档(需求文档)不受信任。这可能比没有文档更糟糕,因为这只会使读者感到困惑。