Home > Archive > PHP PEAR Questions and Answers > January 2005 > Re: [PEAR-QA] some action
You are viewing an archived Text-only version of the thread.
To view this thread in it's original format and/or if you want to reply to
this thread please [click here]
| Author |
Re: [PEAR-QA] some action
|
|
| Arnaud Limbourg 2005-01-21, 3:56 pm |
| > Hi,
>
> I wanted to bring up the following idea.
>
> 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/packa...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.
Arnaud.
| |
| Paul M Jones 2005-01-21, 3:56 pm |
| Arnaud Limbourg wrote:
>
>
> 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
| |
| Paul M Jones 2005-01-21, 3:56 pm |
| Arnaud Limbourg wrote:
>
>
> 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
|
|
|
|
|