wiki structuring Re: [PEAR-QA] some action

Paul M Jones wrote:

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:

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.

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.

I disagree. I think its all cool for people to write examples in their chosen format. But for API documentation a standard is a requirement. Even if it will never be exported to docbook. The key point is that per package you will end up with 5-10 tutorials each with the size of one of the DB intro chapters. Thats all manageable. However the API documentation is going to be many more pages. They need to be structured by class. They need to be easily linkable from the examples. If you have to guess how the person decided to name the page all the time. If you want to quickly look up things and one guy puts the output parameters at the bottom and the other puts them at the top behind the input stuff you have a horrible user experience. To conclude: Free form for verbose text. Strict rules for reference docs like API's The good side effect is that porting text to docbook is going to be fairly easy and structured API docs should be possible to handle automagically. regards, Lukas