Re: Re: some action

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