[prev in list] [next in list] [prev in thread] [next in thread] 

List:       ojb-dev
Subject:    Getting Started documentation (ojb-blank update)
From:       Bruce Lee <brucelee_1969 () yahoo ! com ! au>
Date:       2004-12-30 23:45:30
Message-ID: 20041230234530.50982.qmail () web90004 ! mail ! scd ! yahoo ! com
[Download RAW message or body]

 --- Thomas Dudziak <tomdzk@gmail.com> 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:
> ojb-dev-unsubscribe@db.apache.org
> For additional commands, e-mail:
> ojb-dev-help@db.apache.org
> 
>  

Find local movie times and trailers on Yahoo! Movies.
http://au.movies.yahoo.com

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

[prev in list] [next in list] [prev in thread] [next in thread]