| Jesus M. Castagnetto 2004-08-10, 3:57 pm |
| I will not rehash what Joe and Justin have already mentioned, just add some
comments to your msg.
--- Alfonso Baqueiro <abaqueiro@memoria1.com> wrote:
> The documentation in pear site is the kind of API documentation, like
> the java api documentation, but in fact that kind of documentation is
> only useful if you have a knowledge of the purpose of the clases and the
> problem that they try to solve.
>
> Another failure in the documentation is there are a lot of packages that
> does not have documentation.
This *is* Open Source, so if there is a lack that you observe and you know what
to do about it, then it is easy, go to the pear-doc list and ask for karma, and
write the missing documentation. That is exactly how the main PHP documentation
is written. Not always the author of a PHP extension or a PEAR package is the
one writing the docs (or examples), usually it is someone else.
So, if you are up to it, we will be happy to have you helping with the
documentation.
> The utilization of PEAR repository can be improved if is included in the
> documentation some examples of utilization of the classes solving real
> problems, an example is more useful and educative and can give a fast
> general vision of the class utility, that allows to the people using the
> class to hack the code for search details of the class.
See above.
> Other important aspect that can be a plus is if the classes include
> anotations on the analysis of the problem, design decisions, the
> problems find in the implementation and the clever ideas that allow to
> round the problems.
That is not always feasible, nor recommendable. I speak from my own simple Math
packages, in which the algorithm is known, so it will be a waste of time to
reiterate that. For example, I would not expect someone that is not familiar
with quaternions to even look at Math_Quaternions, let alone grok the
algorithms (although I've included some implementation details in the API
docs).
> With who can i discuss this kind of things?
Subscribe or send a message to the PEAR documentation list, ask for an account,
read the information about writing DocBook, get acquainted with the
documentation files layout, and then start contributing.
Paraphrasing some old Smokey-the-Bear cliche: "Only you can improve the PEAR
documentation" :-)
Cheers.
=====
--
Jesus M. Castagnetto (jcastagnetto@yahoo.com)
Research: http://metallo.scripps.edu/
Weblog: http://weblog.castagnetto.org/
PEAR stuff: http://pear.php.net/user/jmcastagnetto
__________________________________
Do you Yahoo!?
New and Improved Yahoo! Mail - Send 10MB messages!
http://promotions.yahoo.com/new_mail
|