Re: Documentation, round 2

At 27/04/2003 12.56 -0400, you wrote:

The singlemost important part of documentation is the first three sentences. These sentences need to describe: 1) exactly what problem this software solves 2) how it solves it in an abstract sense 3) how it differs from other solutions/advantages. For instance, if we take two packages that are in cvs, Pager and Pager_Sliding. I have no clue what the difference between them is. I don't have time to read the source code to choose one, and only knew that these packages help split output up into page-sized chunks because of discussion on pear.dev, otherwise I never would have even known they existed to solve that problem. Perhaps the package creation page should include these three questions: What problem does this package solve? How does it solve this problem? How does it differ from other pre-existing packages in PEAR?

Hi Greg, I agree with you that we devs should spend a bit more time in documenting our classes. I had done something, and you can see it here (on alan's web site): http://devel.akbkhome.com/peardoc2/package.html.pager-sliding.html The problem is that there are already more documented packages in peardoc2 than in the online version, but for some reason still partially unknown to me, they're not available on pear.php.net. I know these docs could be better, maybe with an effective explanation on the differences between the two packages, but you know, one is not really "incentivated" to do so, because his effort won't be seen by the majority of the people. I don't see any hurry to write better docs, if I know they won't be published, and thus they can't be used :-) This is just meant to be a request to php/pear admin to fix the new peardoc2 building system... If Alan, Xavier and/or Mika agree, an effective temporary measure would be mirroring on the pear official site what they are doing on their own sites, at least until the internal building system is up. (hint! hint!). Best regards, Lorenzo