Re: New Package: HTML_DB

On Fri, 25 Apr 2003, alan wrote: > >DB_DataObjects: Documentation opaque to impenetrable. > > > I'm open to ideas on docs for dataobjects - if you have any solid > suggestions let me know OK. Here are my main problems with DBDO docs: * The examples are all just chunks of code. I'll pick on the first one people come across, because, well, it's the first example they'll see. There are two one-line comments in the whole of the snippet, and neither of them tell the reader what exactly is happening. You're playing with a lot of fairly high-level concepts straight off the bat. It doesn't help the user with understanding what's going on - it just sets the confusion level high early on. You get into the thick and heavy of the config items early, without a clear definition of what it is that we're using this thing for. This is mainly because you're describing things top-down, instead of bottom-up. The example code in the introduction, for instance, uses the Persons DBDO class before it's defined. So the question is asked in the reader's mind, "Is DataObjects_Person something that's already defined?". You might want to talk about subclassing first, including what methods you'll be likely (likely, remember - not all possible members, just the basics) to overload, then the Person example (with gratuitous comments). *Then* go on to using it, with the SQL code generated (which, by the way, shouldn't have php code tags around it). A lot more description of the theory and mechanics of DBDO operation would help, too. Directory structure is paramount - unless I know, in advance, that schemas are stored in a certain directory, with the name corresponding to the class name with a .schema extention (of whatever it does), I'm going to be baffled when you're discussing schema locations (for instance, the reader might ask "WTF is a schema in this context, and why do I need a location for them?"). I'm pretty sure that all the information one might ever require is in the DBDO docs, but it's hard to find. Unless I'm pretty sure I'm going to need the full power of DBDO, I'm going to write my own (and I have, actually, although it's limitations are many and varied). And I can't really actually determine what the full power and limitations of DBDO are at a quick read, since there's no "Limitations" section in the manual. The introduction section shouldn't have any code, ideally - stick that in a separate "gentle example" section. Give me the goods and bads of DBDO, in simple technojargon, in the introduction. Answer the question "Does DBDO fit my needs?" before I hit any code. If I don't know whether it's any good, I'm going to skip the code, because I'm still trying to work out whether I should be drooling or googling for something else. -- ----------------------------------------------------------------------- #include <disclaimer.h> Matthew Palmer, Geek In Residence http://ieee.uow.edu.au/~mjp16