SeanCoates发表了一篇关于DocBook和PEAR上关于使用wiki来编写包文档的各种提案的咆哮和博客条目。
可能需要了解一些背景知识。许多PEAR开发人员认为DocBook是不必要的困难，并且为编写PEAR项目的良好文档提供了障碍；这实际上是缺少PEAR包文档的最常被引用的原因。许多人实际上创建了wiki，然后他们将其链接到最小的DocBook教程中作为“完整文档”。
建议的补救措施是为每个PEAR包创建一个PEARwiki。然后，计划的流程会将wiki标记转换为DocBook、HTML、PDF等。
Sean抱怨的内容很简单：wiki标记本来就是简单的，而许多代码文档需要专门的wiki标记。此外，DocBook已经准备好进行所需的转换；它是一种结构化语言，旨在处理成各种输出格式。
虽然我在本质上同意Sean的想法，但我仍然觉得DocBook真的很难用。PhpDocumentor在记录代码时提供了一些真正的便利：文档块可以包含HTML，一些简单的内联元素，如{@link}—它们使记录变得轻而易举。但我只是不明白为什么在提供教程时必须切换到DocBook。每当我使用它时，我发现我必须重新编写我已有的或其他人已经编写的一组教程，以便获得正确的格式，而且我必须完全改变我的想法以适应一套新的规则和逻辑。
是的，DocBook只是带有文档化模式的XML。但是，我从来没有享受过XML。我觉得它太迂腐了，我不喜欢为了呈现HTML（和代码、XML等）而必须转义出CDATA序列，我不喜欢为每一个都学习新的DTD项目等等。对于配置，我觉得除非您没有嵌套元素，否则没有理由使用XML。说到文档，为什么要使用HTML以外的任何东西？由于HTML是SGML的子集（与XML一样），因此没有理由不能将其本身转换为其他格式—对于大多数PHP开发人员而言，HTML是众所周知的，而XML/DocBook可能不是。
DocBook是否困难可以从这里一直争论到永远。事实是它被认为很难学，因此许多PEAR开发者只是选择不去打扰它。为什么不给他们一个他们可以轻松使用的工具？也许那时PEAR文档的数量和质量会有所提高。
