PaulJones在PEAR项目中写了一篇关于文档的有趣文章，他在文中非常有说服力地论证了将wiki用于最终用户文档。
实际上，我认为最后一点值得重复：使用wiki来制作最终用户文档。我在php|Tropics上和Paul谈过这个问题，我们都非常虔诚地使用phpDocumentor。但是，API文档与最终用户文档有很大不同。PEAR项目的文档问题与这样一个事实有关，即许多项目很少或根本没有最终用户文档——这通常使开发人员难以确定如何使用模块。
经常提到的障碍是PEAR网站上的最终用户文档必须以DocBook格式完成。
郑重声明，我讨厌维护DocBook格式。我使用它为Cgiapp创建了教程，我害怕不得不返回它们来更新或添加新部分。
为什么？好吧，对于初学者：
- 我不是每天都使用XML。如果我需要处理XML，我通常会创建一个模板并用脚本填充它。或者我使用解析器。但我不会手写它。
- DocBook不使用与HTML相同的标签集。这意味着我必须尝试并记住不同的标签，以及哪些在哪个领域起作用。
- 与(2)相关的是，因为可用的实际标签可能因DTD而异，所以VIM没有击键宏创建开始/结束标签。这是我每天编辑HTML时使用的一个功能，它加快了我的写作时间。因此，编写DocBook比编写HTML（或纯文本）要慢一个重要因素。（是的，我可以为常用的标签编写VIM宏，但是我需要学习更多关于VIM脚本的知识，谁有时间？）
- 我已经了解并每天使用HTML。我每天都使用纯文本（我有提到我使用VIM吗？）。我在这些环境中很舒服。我为什么要使用其他任何东西？
但我认为经常被忽视的一点是，PHP是用来创建网页的。让它沉入片刻。为什么PHP项目会鼓励使用Web语言HTML以外的任何语言编写文档？事实上，为什么它会劝阻编写网络就绪文档？
正如Paul所指出的，虽然wiki可能无法满足所有文档目的，但它们对大多数来说已经足够了。在大多数项目中，您不会调整表格来记录项目；多级标题、段落和一些列表元素就可以了。Wiki可以做所有这些事情。它们使这些事情可以轻松完成，并且可以立即获得结果（而不是像PEAR网络文档那样每天一次，它必须从DocBook编译）。
我的建议？由于DocBook可以导出为几乎任何东西，将PEAR文档导出为wiki格式，然后将wiki用于除了最复杂的文档之外的所有文档。用HTML编写复杂的文档，或者，如果您真的觉得需要一种与输出无关的格式，那么请使用DocBook。（我的猜测是，如果实施了上述内容，一年多后我们将看不到太多DocBook。）
也许通过减少创建可用的最终用户文档的障碍，我们将开始看到PEAR上文档的激增，以增加已经出现在那里的优秀代码。
