Or better yet, this could be an optional part of package.xml
s/optional//
- Davey
Greg Beaver wrote:
Hi all,
As a documentation freak of sorts, I would like to point out that the only reason I ever begin *investigating* using a new project is when it is well documented.
We PEAR developers need a bit more ambition: don't write code for other people unless you REALLY want them to use it :). If you want people to use your code, documenting is PART of developing.
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.
These three sentences should appear prominently on every package page, and be indexed for searching online, as well as appear in a single page listing every package in PEAR (this data extraction should be possible using DocBook, I'd imagine)
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. In my grammar, a pager is an annoying beeping device rendered obsolete by cell phones :).
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?
Or better yet, this could be an optional part of package.xml
Greg