Re: some action

Arnaud Limbourg wrote:

Once we have the wiki up. We should define rules on how documentation should be written in the wiki. Preferably in a manner that will allow us export to docbook (immediatly or eventually). Once we have define this we will make a call in pear-general for "user appreciation" or something like that were we suggest that every user do one of the following for every 3 packages they have used in a project recently: - write a chapter on how to use a particular feature of their favorite package (similar to http://pear.php.net/manual/en/package.database.db.intro-portability.php) - write API documentation for 5 methods As documenting things is likely to bring up some questions or even bug reports due to closer examination of special cases this will be followed up by a "developer appreciation" bug hunt. Where developers can adopt packts of 5 open bug reports. The bug packages will be put together by the QA team and should be coherent (either on a specific package, or a specific issue spanning multiple packages etc). Developers are of course free to pick up more bug packs. Also lead maintainers are allowed to opt out with their packages. Those who dont opt out allow the person who took up the pack to mess around with the bug report etc. They dont grant that person to mess with CVS though (although they may do so if they wish), so the person handling the bug pack should submit patches inside the bug report. The maintain is then free to apply the patch within the regulations that we set when we founded the QA team.

Hi, I agree that rules need to be defined on how documentation should be written. I also think we should define a minimum structure for every package area, it will help having a minimum of consistency throughout the wiki. I started writing a draft document, the minimum structure should be very simple so it is not a burden. As to how people can contribute the idea sounds good, I would separate the contributions rules and the call to ask for contributors. That is, having one document explaining the wiki rules and another for the call to contributors.

Rules are good, but too many rules is bad. You need some rules for broad structure, but too many will bog us down. Setting too many rules in advance will stifle innovation and decrease willingness to participate. We will have a relatively restricted environment for the wiki (i.e., no anonymous editors, authenticated editors via PEAR login only), and I think that is rule enough. I say let the writer-contributors come up with their own solutions. Let them pick and choose from each other's examples as the volume of content increases. Once a common practice becomes clear (say, after 6-9 months) codify that as our standard. It worked for English Common Law, it will work for us. One of the points point of the wiki is that it is more free-form than the highly-structured DocBook; whatever happens on the wiki may or may not be translated into the formal DocBook documentation. I think of the wiki not as the pre-DocBook version, but as its own parallel thing. If we can evenutally use it as a source for DocBook, great, but I believe its best purpose will be found by the end-users, not by PEAR Group or PEAR QA top-down dictate. -- pmj