I didn't mean it like that. More like Javadoc or phpdoc type comments right in the source code files. Having separate documentation files in the project tree isn't much better than having them in a separate site.
Yes, but this kind of documentation is not enough. This topic has been discussed before but what comes out is that phpdoc is nice for developpers. End-users need other type of docs, tutorials, quick start, younameit.
But in addition to that, for collaborative documentation efforts, a live wiki of some sort should augment the static package docs. This is one way to let other people help with documentation of a package; the benefits are instant feedback and low barriers to entry (Wiki is relatively easy, DocBook is relatively hard). As the maintainer wishes, he can edit the live docs that have edited by contributors, roll a new docs/ directory from it, and add the new docs/ directory in his new package. This should be significantly easier than writing DocBook docs.
DocBook is hell. I write my documentation in Docbook, and I barely scratch the surface of it. I agree an alternative may be interesting. However, I don't see the barrier to entry for documentation writing lying in the documentation format. There's a much larger barrier in the understanding of the code. That is why I believe documentation must be the responsability of the developer, not some magic helping hand. Noone likes writing docs, much less other people's docs.
A developer should write some doc yes but external people like users have another view and can make very good documentation (that's why there are some technical writers out there :)
The current docbook format is a barrier to documentation writing I believe, cost is too high. Documentation from a user point of view does not especially means a deep understanding of how the code works. What matters is what it does rather than how it does it.
Your comment, however, sparked another idea. How about having comments in PEAR documentation? User comments are one of the best features of PHP's docs. We should be able to replicate that.
This idea has been floating in the hair for a while :)
Yup. We disagree on the identification of the barrier to entry.
Summing up: I believe this is false for the "core" documentation. These reference docs and core tutorials must be written by the code author. On the other hand, wikis are probably very good for "complementary" documentation: extra explanation of library behaviour, alternative usage and bug workarounds, much like what happens in PHP's interactive docs or Postgresql's interactive docs.
Wikis might work very well for non-reference docs, however. I don't have a strong opinion there.
Cheers,
Arnaud.