Re: Re: Livedocs

On Feb 23, 2004, at 10:56 AM, Sérgio Carvalho wrote:

Paul M Jones wrote:

There's also the option of using a Wiki for this; have forwarded a solution to Lukas and Pierre that uses Text_Wiki for parsing, and have added an pseudo-hierarchical mapping system that generates navigational elements (tabs, sidebars, etc). If anyone would like to see it I can set up an open, anonymous demo.

I disagree. Reference docs should accompany the code, and this is rather difficult to keep up with a Wiki.

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. 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. 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). 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. -- Paul M. Jones Savant: the simple alternative to Smarty. http://phpsavant.com/