I Have read the IRC log and the summary of the PEAR Meeting.
| From: | Christophe Gesché | 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