Getting Started documentation (ojb-blank update)

[Bruce Lee <br...@yahoo.com.au>]

 --- Thomas Dudziak <to...@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

Re: Getting Started documentation (ojb-blank update)

[Bruce Lee <br...@yahoo.com.au>]

 --- Thomas Dudziak <to...@gmail.com> wrote: 
> Sorry that I answer this late, but at the moment I'm
> somewhat buried
> under work, so longer answers take a bit longer ;-)

That's OK Thomas, we're all very busy I suspect. I was
beginning to think that no-one was interested... but
as long as we get there in the end :-)

I will make a more detailed response to the issues you
raised soon, for now I just want to bring to your
attention (if it hasn't been already) the "missing"(?)
WAR target from the ant build script in ojb-blank. 

In the reference guides, under Deployment->Deployment
in Servlet Based Applications, one can find the
following text:

 "By executing ant war you can generate a sample
servlet application assembled to a valid WAR file. The
resulting ojb-servlet.war  file is written to the dist
directory. You can deploy this WAR file to your
servlet engine or unzip it to have a look at its
directory structure. you can also use the target war
as a starting point for your own deployment
scripts..."

but running ant -p in the top-level directory of
ojb-blank shows that no such target exists. Did it get
removed for a reason? It would be very helpful to see
the resultant .war file for newcomers trying to get
the example servlet running.

Specifically, I have been fiddling with the Servlet
tutorial example and (following the structure of other
examples I have found online) am fairly certain that I
have a correct structure for the classes, library
files and deployment descriptor under Tomcat, yet I
cannot get the servlet to read the repository
descriptor.

Another line from the above source says:

" Deploy  OJB.properties   and  repository.xml   with
your servlet applications WAR file.
The WAR format specifies that Servlet classes are to
be placed in a directory WEB-INF/classes. The OJB
configuration files have to be in this directory."

When I place the configuration files in the specified
directory, the servlet no longer reports that the
repository data cannot be found and instead reports
that it cannot be read. 

Can we have either, or both, of:
a) the WAR target back in build.xml
b) the reference guide made clearer so that we might
divine the correct structure and write our own WAR
targets?

Cheers, 
Bruce. 

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

Re: Getting Started documentation (ojb-blank update)

[Thomas Dudziak <to...@gmail.com>]

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