Re: Re: hosting packages on external VCS sites

On 3/24/07, Arnaud Limbourg <arnaud@limbourg.com> wrote:

David Coallier wrote: The choice of using docbook might be hard to some people to understand as this is a relatively new (~~ new is a big word) structure/language for many people. However, this is a documentation standard and we can state also projects using it as such as the Zend Framework. They actually use a wiki now I think.

Depends which projects, they still all have docbooks. They have all the documentation tools but they also have people paid to maintain it :)

Also, concerning using svn or cvs, this is also something we have discussed for the past what.. year or so ? we even had a page and I encourage you all to put your thoughts/facts there: http://oss.backendmedia.com/PHPSVN/ Moreover, in order to have a good wiki, a project needs a wikimaster. But this is currently being discussed and as soon as the pear group is elected we will come to a conclusion on the documentation tools, etc. This is personally my top priority if I am elected :P More than a wikimaster I think having a wiki means having a team of editors otherwise the structure will get messy. Wikimaster, wikimasters (people that maintain the sections, packages

infos, etc) so yes.

A year and a half ago the wiki implementation (yawiki) I glued to pearweb setup a common structure for all packages, the maintainer could of course change anything. Having a wiki means writing howtos for developers who want to add documentation so that we have the same structure across packages. We are currently discussing about: ----------------------------------------------- Bug reporters; Wikis; Forums; etc. There is a lot of things that are going to be improved in pear within the next few months and I hope to see you all participate in all that :). The goal we are trying to achieve is to first, make the task of writing docs, not a problem but something that can be done without pain and too many problems. We have to get the idea that writing docs is painful (even though it is in any language possible most of the times) because it is extremely useful. more ? yes.. I can't agree with you Markus when you say that writing docbook for one package is overhead, I mean look at this page: http://cvs.php.net/viewvc.cgi/peardoc/en/package/text/ Look at text-captcha-numeral.xml and the folder. This has three pages and it is not extremely complicated to use and code. What I really like about docbook is not it's simplicity but actually is complecity, I mean book companies use this for some developers (like latex), frameworks use it, other random non-computer projects use it. This is a worldwide documentation language and this is the reason why it was built. It might take one or more hours to understand it, but learning it to a certain degree that you can write at least simple docs is rather easy. Docbook makes it easier to write some tools as well because of its structure. Having a revision tracking mechanism on a wiki is possible but I suspect it requires quite a lot of work.

Oh yeah

Arnaud.

-- David Coallier, Founder & Software Architect, Agora Production (http://agoraproduction.com) 51.42.06.70.18