--- Thomas Dudziak <[EMAIL PROTECTED]> wrote: > Bruce Lee wrote: > > >Hello, > > > >I would also be interested in helping rewrite some > >parts of the documentation, assuming you are > >interested, but not quite sure how to go about this > in > >terms of making submissions. Advice appreciated. > > > > > We're always interested in help, especially for the > documentation, so > submit anything that you got to this list :-) You > can send HTML or text > or - if you feel a bit more adventurous - in Forrest > format > (http://forrest.apache.org) which is really the > source format that we're > using to generate the doc. >
OK, well I'm happy to make contributions in Forrest formatted XML if that's what you prefer but first feel that I'd better check to make sure that I'm not going to tread on any toes, and that people think my ideas are appropriate. I should say up front that I'm no Java guru. I've been writing web-database systems for a few years using (primarily) PHP/MySQL, and am reasonably good at that. I have tinkered with Java over the years but never used it in a serious project. Recently, I had an idea for a new pet project, which I could easily build using the stuff I already know but thought it might be nice to expand the horizons a bit and try implementing it in Java. I drew up a database schema and had just started wondering about how Java objects might sensibly interact with a relational database when I, more or less accidentally, stumbled across the OJB website... So, last week I discovered OJB, Ant, XDoclet, Torque, JUnit and Forrest. I've been using Eclipse for about twice that long. It's been an interesting fortnight :) During that time (with a lot of fumbling around) I have managed to build db-ojb from source, get tutorials 1 and 2 running under ojb-blank and implement toy (albeit multi-table!) MySQL database which I can query using ODMG applet, and which, thanks to your own great examples, even features a couple of JUnit tests. So far so good. And I guess the thing to note is that the documentation is good. Good enough to get a complete newbie that far, at least. My initial interest would be in redrafting parts of the 'Getting Started' document to reflect the things that are probably too simple for more experienced people to have noticed as lacking, but would make life easier for Real beginners. A good first step would be basically just make it easier to read. At some point that involves restructuring, and I guess that somewhere, sometime you have made policy decisions about what you want to see in the docs, and how you want the public face of OJB to appear. These are things that someone new cannot know without asking. Are there written guidelines on this anywhere? Moreover, documentation needs to reflect the current state of the code, and some of the suggestions that I have in mind for making the documentation more accessible would entail (minor) changes in the associated tutorial code. Again, it seems likely that you have things structured the way you do for a reason; perhaps one which is not clear to me because I am so inexperienced here. So, I guess what I'm posing as a question here is: Are you interested in lowering the bar for initial entry to OJB? A (non-exhaustive) list of some of the things that I would propose (if it were up to me) would be: In the initial Getting Started document: 1. The content is unnecessarily complicated, and the structure could be improved. a) Setting up OJB is non-trivial. But this is even more reason to make the first exposure as Vanilla as possible. Non-committal evaluators of your technology need to be encouraged by the ease of their initial success to learn more about how they can leverage OJB and spread the word about your work. b) There is potential for newcomers to be overwhelmed with new ideas. A good approach to this would be to make the initial contact *descriptive* of what is happening under the bonnet, minimizing the intervention required to make things work. There will be plenty of time for tinkering later. With that in mind: 2. Ojb-blank should (as far as possible) run out of the box. a) Apart from making OJB more accessible this way, it will also (I assume) remove some of the noise on ojb-user resulting from new users simply trying to configure too many unfamiliar things at once. This gives you a break too! b) Working sample code should come prepackaged in src/java. It's simple for experienced users that want to use ojb-blank as a template to delete this, or substitute other more advanced samples, and removes an extra obstacle to new users. Other, more advanced sample code (or examples requiring additional libraries) can be made available in an appropriate fashion, properly introduced in conjunction as a user works through the tutorials. c) Encouragements to set up and use other O/RDBMSs should be relegated to a second stage of familiarization. Ojb-blank is (almost?) completely preconfigured to run HSQLDB, why not stick with that in the initial pass? Save all the configuration detail for a second document. In the first instance users just need to get broad concepts. The impatient/experienced will drill down to get what they want anyway. 3. Tutorial source code should be in sync with the tutorial documentation. a) There are undocumented examples in the tutorial source packages. It would be nice if they were either discussed in the tutorials or made available separately with an explicit note saying that they are not tutorial examples but are made available for interested parties. This avoids clutter, potential confusion, and may just encourage someone to add a new tutorial document! b) Conversely, in places the documentation discusses features which no longer seem to exist in ojb-blank. The build targets in the JDO tutorial spring to mind. There were other instances too, that I forget offhand. 4. The tutorial documentation that exists does not highlight some of the excellent examples in the OJB code! a)It would be nice to rework parts of the tutorial documents to reflect the actual (nicely commented) code in the tutorial sample source files, rather than the more generic reference code they (the documents) currently use. b)I think it would be excellent to write a tutorial highlighting the use of JUnit in the OJB context, based on those in the source distribution. 5. Tips for getting the sample code running in Eclipse would be good, although I don't really see that as a priority for OJB, it certainly would have saved *me* some frustration! Anyway, you get the idea. I'm not only in over my head but frustratingly pedantic to boot :) Happy to discuss any of these points (and any others raised) with interested parties. I will not be offended if you are not interested in any of this, and can well understand why you may consider it irrelevant to OJB goals. I'm going to be away for a couple of days but would be happy to provide Forrest produced drafts of Getting Started for inspection/discussion early next week, if no objections have been raised before then. (The subtext here, of course, is that I'm also going to post lots of ignorant-newbie questions as to why I can't get foo to bar like it should. After all, I have a new pet project to work on :) Hope you have a Happy New Year, wherever you are! --------------------------------------------------------------------- > To unsubscribe, e-mail: > [EMAIL PROTECTED] > For additional commands, e-mail: > [EMAIL PROTECTED] > > Find local movie times and trailers on Yahoo! Movies. http://au.movies.yahoo.com --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
