db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thomas Dudziak <tom...@gmail.com>
Subject Re: Getting Started documentation (ojb-blank update)
Date Thu, 06 Jan 2005 23:27:31 GMT
Sorry that I answer this late, but at the moment I'm somewhat buried
under work, so longer answers take a bit longer ;-)

> 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 think we here all try to be objective, so treading on toes should
not be an issue ;-) And personally, I think the questions and ideas of
someone new to something are always worth listening to because they
often show the goods and bads.

> 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.

Well, you took the hard route :-)

> 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.

We're aware that the documentation is a bit lacking esp. for
newcomers, but IMO writing good documentation is hard and a continuous
refinement process. The problem is that we are no newcomers so it is
more difficult to see where the problems are (which is where you come
into play ;-) )

> 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?

No,  there are not as far as I'm aware. Simply post what you think so
we can discuss it.

> 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.

Yepp, the documentation is slightly out of date in regards to the
changes since version 1.0.0 (and even more so for the CVS head, but
for a different reasons as this is work in progress).

> 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.

Yes, that's true. Any ideas of a better structure, e.g. a step-wise
structure like The Java Tutorial or somesuch ?

> 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.

Well, you've started with building OJB from scratch which isn't the
easiest route by far. Once the 1.0.2 is up, there will be pre-built
tutorial apps for tutorial 1 (PB) and 2 (ODMG) which are based on
ojb-blank, so this should be easier (if properly reflected in the
tutorials themselves).

> 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.

I'm not so sure about the value of something like this. Mainly because
OJB is a library, and I for one don't learn how to use new libraries
by running applications that use the library but rather by creating
some small example apps that exercise the library. But maybe
that'sjust me.
Also, IMO ojb-blank is quite easy to use: just drop in source code
with XDoclet tags and run the Ant script. With a tiny bit of
configuration in the build.properties, you get a ready-to-run app even
with shell scripts to start it. E.g. I use it this way to test source
code that is posted on the list to manifest and find/debug errors.

> 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!

AFAIK most of the 'noise' on the list is concerned with configuring
OJB for webapps. I'm in the process of adapting the tutorial 1 as a
webapp (Struts-based) to alleviate this.

> 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.

See above.

> 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.

Hmm, yes, could be one of the later (optional) steps in a step-wise tutorial.

> 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.

As I said, the tutorials are slightly out-of-sync ...

> 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.

True.
 
> 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.

Don't know. Writing unit tests that use OJB mainly require knowledge
about how to use OJB (which is not testing-related), and for the rest
there is a bit of doc here:

http://db.apache.org/ojb/docu/testing/testwrite.html

> 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!

Indeed. I'd like to provide a ready-made run configuration but for
whatever reason that is not possible with Eclipse. But a howto about
using OJB and esp. ojb-blank with common IDEs is a good idea

> Anyway, you get the idea. I'm not only in over my head
> but frustratingly pedantic to boot :)

IMO that is a good character trait when reviewing software :-)

> 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.

Keep posting! I'm trying to work on what you've suggested (as my time allows).

regards,
Tom

---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org


Mime
View raw message