Re: New Package: HTML_DB

On Fri, 25 Apr 2003, Matthias Englert wrote: > > DB_DataObjects: Documentation opaque to impenetrable. > > It could be simpler... maybe, but it's not that bad, is it? It took > me about ten minutes to start using DataObjects. I handed the docs to 6 fairly switched on junior developers, after 3/4 of an hour, they decided to roll their own. I've also gone over the docs several times, and while with effort I could probably make it sing and dance, I (1) don't need all of the hoohah that DBDO can offer, and (2) do not have the time to decipher difficult docs. I have to deliver something, now, and it's easier to roll my own and worry about tomorrow tomorrow. Before someone stomps on my development style, I'll tell all of the theoreticians of perfect development methodology to FOAD or get a job in the real world. A note to all of the PEAR authors out there - your documentation has to tell the reader, straight off, that using this class is going to be quicker than writing their own functional equivalent. It then needs to back that up by showing them what they need to know, in clear, concise blocks. My general recommendation for documentation style is: Introduction: No code, just an outline of the features and limitations (very important to tell me what it can't do). Just touch the high points. If you've ever written real reports, your PEAR intro should do the same as what a real intro does - tell me what I'm going to get in the rest of this doc. That way I can stop wasting my time now if it won't do what I want it to. Example: Simple example, *heavily* *commented*, showing perhaps the basic structure of a typical usage. Major Points: Describe each and every major aspect of the class system you're documenting, in a tutorial-like style. I'll commend the authors of the DB class system here, they've done a beautiful job of it, along with my next part... Reference: Every single public method and property, listed and described in excruciating detail. Usage example if it warrants it, but *only* if it warrants it. If you have multiple classes, collect all of these by class. I'll give a round of applause to the authors of the documentation for the DB classes - it was a nice, easy to follow intro to what it could do. I'd like to apply a brickbat to whatever clod(s) wrote the docs for the logging classes, *especially* those in pear.php.net (the ones on uchile.cl seem to at least have an example now, but they still suck). May I ask where a poor, hapless developer, up against the wall, is supposed to work out how to write a log message using your class? Oh, there it is - in the source code. Many paragraphs were expended proving you know "software engineering design patterns", but you couldn't put 3 lines somewhere saying "you send a message to the log with the log($msg, $prio) method" and some talk of what messages and priorities actually are. Let the return flames roll on in. -- ----------------------------------------------------------------------- #include <disclaimer.h> Matthew Palmer, Geek In Residence http://ieee.uow.edu.au/~mjp16