Re: [PROPOSAL] DB_Simple

Hi, Alan --

<not a flame> The following is _not_ a flame against the DB_DataObject and MDB authors. I played with both MDB and DB_DataObject for about 20 hours each, and found the documentation and examples somewhat lacking.

You know what's the response to that :)

Yeah, yeah... ;-) <rant> But nobody is going to write documentation for someone else's package. Everybody wants to code, nobody wants to write docs, especially not for someone else: it takes time to understand the class, and then it takes time to write them up, and then it takes time to make sure that what you wrote actually corresponds with the class behavior ... and that's just the basic documentation, much less a tutorial and example. Docs are boring, docs are not sexy, docs are not high-profile achievements, and nobody wants to do them beyond the absolute minimum. In short, docs are the responsibility of the author, not users. </rant>

If the documentation is 'lacking' suggest improvements

OK: how about a detailed explanation for a brand-new user on how to extend DataObject both with a .ini file, compared with how to do it by embedding the .ini data within the class. Which properties control what? How does one build a calculated column? How does one build multiple queries to be used within the class to retrieve different columns of data? Explicit instructions and examples.

The .ini file format for DB_DataObject is not that well explained,

It is mentioned (both on the required configuration options and createTables docs), though not in much detail

Exactly my point: for such an important part of the class, I would think it deserves more than a mention.

I guess that as it's autogenerated, it's not normally neccessary for users to know too much about it (other than it exists..)

Did I understand you to say the .ini file is autogenerated? (More doc suggestions follow.) Autogenerated from what? Can one hand-write the .ini file? Does one *have* to autogenerate a extension DataObject, or can hand-write the extended class? How does one autogenerate it anyway? How does one hand-write it? What are the strengths and weaknesses of each approach? What pitfalls should one look for? Is one "approved behavior" and the other proscribed? These are the kinds of "for dummies" questions that docs need to answer -- and these kinds of questions are answered for DB_Simple in the proposal, which is not even a formal piece of documentation.

Code authors have better things to do than explain our methods and procedures to newbies, but to aid developers in the use a package we need to do just that (i.e., write our docs "for Dummies" and "for people who have no time" and "for all sorts of possible cases"). If MDB and DB_DataObjects had better docs,

http://pear.php.net/manual/en/package.database.db-dataobject.php I'm not sure, but I would (blowing my own trumpet) say that DataObjects, docs are some of the best in PEAR... - but I would welcome ideas for improvement... :)

You are right to blow your trumpet. They are good docs, for PEAR. But, to paraphrase Ambrose Bierce, that's akin to being the coolest county in Hell (not Dante's Hell, either ;-).

That is why I propose DB_Simple: it's easy to get started with, it's well-documented internally, and if it is accepted I will deliver additional high-quality external documentation. [1] Those of you who have seen the Contact_Vcard_* docs know that I am as good as my word when it comes to extensive instructions, explanation, and examples.

The trouble you get into with this, is that if you start with a simplified version trying to merge features of other packages that already exist.. eventually users start asking.. 'can you add this.....' etc. and it grows..

True enough ... but that's an exercise in discipline for the developer. This may be off-topic, but if the package lead doesn't think a class should be doing X, then no amount of user requests should shake you. (Of course, if it's smart or useful, you might be wise to do it.) As far as growth is concerned, is it bad if a new package grows to eclipse an previous package? (I'd suggest, if the existing class was that useful and extensible, it would have grown instead.) ... sorry, not trying to be petty and argumentative. I think I have turned this into a "PEAR documentation and usability" thread. :-( (But seriously, am I the only one here who thinks this way about code projects with respect to end-user docs, examples, and tutorials? Hello? Is this thing on? ;-)

Effectively what you have today is what DataObjects was about 3 years ago..... (+/- some minor features..)

DataObject was doing automated table creation, pre-defined selects, automated validation, datatype abstraction, et. al. three years ago? Then why does it not do so now? _______________________________________________________________________ Paul M. Jones Savant: the simple alternative to Smarty. http://phpsavant.com/