Re: API presentation vs API atoms description. Was: [PEAR-QA] Documentation..

Anatoly Techtonik wrote:

Hello Greg,

symbols. I need more time to get correct information, because I've got a lot of superfluous data and that is inconvenient. Like spam. =)

GB> This is the first and last time I will hear years of work referred to as GB> "spam" GB> Right? Nope. You've taken that too personal. I said that I said. Nothing more. And I

I accept your apology - consider it verbal sparring, nothing more.

haven't said about your years of work being spam. I've only mentioned, that there are other ways to present package API information, which are more convenient for ME. As a reason for such sympathy in comparison with your presentation format I brought this simple methaphor that XML-RPC tutorial-style documentation is organized better by leaving only one learning line to complete package picture and thus leaving all confusing stuff out of readers attention. "spam" is "confusing stuff" in this context.

I do think that pearweb suffers from its current completely inflexible layout. One of the best things about tools like phpDocumentor is that if you dislike the layout, you can very easily take an existing template and modify it to create a different one, including re-formatting where information is displayed. with docbook, this is completely impossible without learning an archaic dsssl language that nobody seems to be able to read. It's like the old medieval Catholic masses where the priests spoke in Latin and nobody had any idea what they were saying :).

You have one line - you follow it until the end - you've got whole package idea and a bunch of ways how to move on with this package. You have multiple lines - you follow constructor description, then some methods description until you find one way to solve your problem. You can read all methods descriptions and don't get a picture. If you can place a voting somewhere - you will get a real statistics about originality of my POV.

In my opinion, original ideas have no significance in coding. Original *work* does matter :). PEAR suffers from a glut of ideas and a dearth of people willing to go in the trenches and make them happen. Having said this, perhaps your idea is the best way to document. In between a full-time concert performing career, maintaining my quartet's website, writing unit tests for PEAR 1.4.0 (I'm up to about 80% done with 467 tests written), continuing with fixes to pearweb, designing a new pear server for channels, upgrading the web installer, upgrading PEAR_PackageFileManager to support package.xml 2.0, doing any work at all on phpDocumentor, finishing unit tests on Game_Chess, and oh yeah living the rest of my life, I'm sure I can find time to redo the docs for PEAR_PackageFileManager that will provide exactly the same content but in a different more snazzy look. Not :). Greg