Re: Re: Livedocs

Paul M Jones wrote:

I partially disagree with your disagreement. ;-) Certainly docs should accompany code. It is trivial to have PageName.wiki.txt in the docs/ directory for as many pages as you like; Text_Wiki can parse them into (currently) XHTML, (near future) RTF, and (undetermined future) DocBook, PDF, etc as one wishes.

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.

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. 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.

To sum up my argument: barriers to entry for DocBook documentation now are very high (get a PEAR account, learn DocBook, submit to maintainer, wait for maintainer to commit, wait a week for docs to get generates). This is why PEAR documentation is so lacking; it's too hard to work with. Barriers to entry for Wiki documentation are low to moderate (get a PEAR account, learn Wiki, edit the page, the page is "live" right away, can then be converted to any other format you like).

Yup. We disagree on the identification of the barrier to entry.

Incidentally, this is why I like Wiki (and why I wrote Text_Wiki in the first place). A Wiki makes it very easy to collaborate on documentation, distributing the workload and getting many people ("more eyes == better results") involved interactively and with instant results.

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, Sérgio Carvalho