Greets, I've been tasked with learning Rose, so this is my one chance to approach the documentation naively. My first impression is that it seems admirably thorough but encumbered by well-meaning excess in places.
Much of the documentation begins with scene-setting. For instance, Rose::DB::Object::Tutorial begins with an INTRODUCTION, followed by the establishment of CONVENTIONS, followed by a Preface. I suggest that the "conventions" material be cleared from its current position. Moving it to a footnote, to a separate document a la references to the "Rose Development Policy", or perhaps even omitting it entirely would allow the substance of the tutorial to rise to the top, improving clarity, brevity and immediacy. Consider, for example, how much is really gained by admonishing users to 'use strict' and alerting them to the fact that such declarations will be missing from the example code. Without this tidbit, how many Rose users will fail to 'use strict' because the examples do not? I believe that the answer is: so small a number that the advice does not justify the precious space it takes at the top of the Tutorial. Subjecting other material to similarly merciless review reveals other opportunities for streamlining. In my opinion, the entire "Introduction" section of RDBO::Tut can be stricken. This document provides a step-by-step introduction to the Rose::DB::Object module distribution. It demonstrates all of the important features using a semi-realistic example database. This tutorial does not replace the actual documentation for each module, however. The "reference" documentation found in each ".pm" file is still essential, and contains some good examples of its own. This tutorial provides a gradual introduction to Rose::DB::Object. It also describes "best practices" for using Rose::DB::Object in the most robust, maintainable manner. If you're just trying to get a feel for what's possible, you can skip to the end and take a look at the completed example database and associated Perl code. But I recommend reading the tutorial from start to finish at least once. The examples will start simple and get progressively more complex. You, the developer, have to decide which level of complexity or abstraction is appropriate for your particular task. Of the information in those three paragraphs, how much has already been conveyed simply by the titling the document "Rose::DB::Object::Tutorial"? And of what's left, which sentences contribute meaningfully to a better understanding of Rose? Why not simply start with the material currently labeled Preface? Cheers, Marvin Humphrey Rectangular Research http://www.rectangular.com/ ------------------------------------------------------------------------- This SF.net email is sponsored by DB2 Express Download DB2 Express C - the FREE version of DB2 express and take control of your XML. No limits. Just data. Click to get it now. http://sourceforge.net/powerbar/db2/ _______________________________________________ Rose-db-object mailing list Rose-db-object@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/rose-db-object
