I Have read the IRC log and the summary of the PEAR Meeting.

From: Date: Tue, 20 May 2003 13:22:13 +0000
Subject: I Have read the IRC log and the summary of the PEAR Meeting.
Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-833@lists.php.net to get a copy of this message
About the doc I would give my opion, And perhaps give some idea. I thing than User would use a package, need some information to work with this package. Structure of knowledge to build a good doc. *C* - The Coder
	      |
	      V
*DW* - Doc Writer
	      |
	      V
*DBW* - the DocBook Writer
	      |
	      V
*PDW* - PEAR DocBook Writer
       |
	      V
*R* - readers
	      |
	      V
*F* - FEEDBACK TO FIRST OR SECOND I think that the 3 writers (*DW*,*DBW*,*PDW*) can be the same person. (It's better, split if *DW* don't know docBook) But different than coder (*C*). The coders team (*C*) must write something for the writer (*DW*). But it's the writer wich write the first public version. (*DW*->*R*) It's important that it's someone doesn't code the package. But the coders (*DW* or *DBW* or *PDW*->*C*) must read the doc and return feedbacks, if the writer has wroten something wrong, to explain it better, Users/readers (*R*) should also return feeback to request more explaination from writers if it's not "easy to read". Some others important infos for users (*R*) wich want use a package are the - doc API, this should be an automated task which follows the coding standard, and requires enough to let the automated task work form the CVS or from the latest releases. - some samples. - some tests - some cases of use <- I think that's very important and would come from users. Users can comment the docs in the online manuel. On the same idea, they would be able to contribute to the doc with the 3 lasts pointed previously listed. As QA exists (or will soon exist) for the package itself, (for PHP or PEAR) It should be great to have a "QA" of each translation. It's easy to be beta-docreader. Just a rules list and a feedback envirnoment. So take some time to write it, can motive user to became beta reader (just because they are able to read it, that will not take too much work than they use for their own usage). PEAR doc is not so basic than PHP doc. Here my english became veyr unsufficient to explain my ideas. Hum in php doc the eplanation talk about an instruction, a function and a parameter. In pear, a package is larger. It's very easy to understand in two line what do an operator, an instruction or a function of PHP. A PEAR package need more info, to explain clearly to the user if it's really what he needs. The Doc must also give an easy way to user to understand quicly if the package matches his needs. But It's not the work of the coder. (where coding became 30% of his work) For these reasons I think we need to give an easy way for a lambda user to contribute with his own experience. If the users have just the possibilities to say "Yes, with this package I can do that.". The next user can better view the usage of the package... And It's a good information for the maintainer wich may get usefull feedbacks to enhance his package. A real complete package need a documentation (as said during the meeting) A Package is a job for a microteam including maintainers (*C*) and (doc writers (*DW*-(*DBW*-*PDW*)) A saw discussion about the word "STABLE" I know that, to be like maintainers usage "STABLE" is the higest level of finality. So this level must have 2 fields. -CODE- and -DOC- And the "package" take the level of the lowest. Spending time on the docs and increasing our experiences we can write a template of content. Formating the content is work for *DBW*- and *PDW*- If "*DW*" is also "*DBW*&*PDW*" he must keep open the the "*DW* work" to other writer. Tools for *C* <-> *DW*-*DBW*-*PDW* : WIKI ? WEBDav ? CVS ? *PDW* -> *R* : Jade *R* -> *C*-*DW* : Web forms If someone have understand, what I have would like to say, I'm already happy. Idea about pear doc Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 8bit I have read the IRC log and the summary of the PEAR Meeting. About the doc I would give my opion, and perhaps give some idea. I thing than User would use a package, need some information to work with this package. Structure of knowledge to build a good doc. *C* - The Coder
       |
       V
*DW* - Doc Writer
       |
       V
*DBW* - the DocBook Writer
       |
       V
*PDW* - PEAR DocBook Writer
       |
       V
*R* - readers
       |
       V
*F* - FEEDBACK TO FIRST OR SECOND I think that the 3 writers (*DW*,*DBW*,*PDW*) can be the same person. (It's better, split if *DW* don't know docBook) But different than coder (*C*). The coders team (*C*) must write something for the writer (*DW*). But it's the writer wich write the first public version. (*DW*->*R*) It's important that it's someone doesn't code the package. But the coders (*DW* or *DBW* or *PDW*->*C*) must read the doc and return feedbacks, if the writer has wroten something wrong, to explain it better, Users/readers (*R*) should also return feeback to request more explaination from writers if it's not "easy to read". Some others important infos for users (*R*) wich want use a package are the - doc API, this should be an automated task which follows the coding standard, and requires enough to let the automated task work form the CVS or from the latest releases. - some samples. - some tests - some cases of use <- I think that's very important and would come from users. Users can comment the docs in the online manuel. On the same idea, they would be able to contribute to the doc with the 3 lasts pointed previously listed. As QA exists (or will soon exist) for the package itself, (for PHP or PEAR) It should be great to have a "QA" of each translation. It's easy to be beta-docreader. Just a rules list and a feedback envirnoment. So take some time to write it, can motive user to became beta reader (just because they are able to read it, that will not take too much work than they use for their own usage). PEAR doc is not so basic than PHP doc. Here my english became veyr unsufficient to explain my ideas. Hum in php doc the eplanation talk about an instruction, a function and a parameter. In pear, a package is larger. It's very easy to understand in two line what do an operator, an instruction or a function of PHP. A PEAR package need more info, to explain clearly to the user if it's really what he needs. The Doc must also give an easy way to user to understand quicly if the package matches his needs. But It's not the work of the coder. (where coding became 30% of his work) For these reasons I think we need to give an easy way for a lambda user to contribute with his own experience. If the users have just the possibilities to say "Yes, with this package I can do that.". The next user can better view the usage of the package... And It's a good information for the maintainer wich may get usefull feedbacks to enhance his package. A real complete package need a documentation (as said during the meeting) A Package is a job for a microteam including maintainers (*C*) and (doc writers (*DW*-(*DBW*-*PDW*)) A saw discussion about the word "STABLE" I know that, to be like maintainers usage "STABLE" is the higest level of finality. So this level must have 2 fields. -CODE- and -DOC- And the "package" take the level of the lowest. Spending time on the docs and increasing our experiences we can write a template of content. Formating the content is work for *DBW*- and *PDW*- If "*DW*" is also "*DBW*&*PDW*" he must keep open the the "*DW* work" to other writer. Tools for *C* <-> *DW*-*DBW*-*PDW* : WIKI ? WEBDav ? CVS ? *PDW* -> *R* : Jade *R* -> *C*-*DW* : Web forms If someone have understand, what I have would like to say, I'm already happy. Christophe Gesché ---- PHPFrance // Claroline

« previous php.pear.doc (#833) next »