Few suggestions regarding Derby Tutorials and Wiki

[siddharth srivastava <ak...@gmail.com>]

Hi

I have been involved with Derby for over a month now.  I went through the
wiki and other resources, to get acquainted. And now that I have resolved my
first
Derby issue, I think its time to put my few cents about the problems I faced
and a few suggestions.

(A) Though I didn't face any trivial problems with the classpath, but I feel
having windows, linux and mac specific commands would be good. Even setting
up classpath for derby from trunk is different from the stable one. I found
that the paths needed to be included manually(/sane) and the jars to be
added after diving deep into the documentation(iirc it was in the doc
related to testing..not well formatted though :) [Not DerbyTesting] )

Though may be we can redirect and link from within devel tutorials rather
than requiring to navigate from the homepage of the wiki.

(B) And even most of the tutorials on the wiki ask to run the script in bin
for automatically setting up the classpath, they do not do so for the trunk
version. May be a warning/note in there would be good or even if we could
have someway to identify which version(trunk or stable) the user is
running,the script can be modified to work accordingly(or warn with
correct guidelines
for trunk version)

(C) In fact a compact tutorial with everything in there would be nice, such
as
 1) when to add various jars in the classpath like junit.jar; at one place
rather than in distinct sections.
2) the problems we face when we run a test and rerun it without removing the
files the previous test produced.
How to avoid it and the best way to do it.
3) Linking to the DerbyTesting tutorial from within that.
4) Even a flowchart on where we can overview the phases one needs to get
through while developing would be good.

My motive in having a compact tutorial is that the user can have an overview
of what things one should need in succession(setting up environment, then
running tests etc). I think Derby Getting started guide would also be a good
place to add/modify these things.

(D) A link for getting started guide on the Home Page and then
allowing the devel/user
to choose among the versions would be good. It looked quite
fearsome when I first reached there clicking on "Documentation" ;-)


Thanks
-- 
Regards
Siddharth Srivastava

Re: Few suggestions regarding Derby Tutorials and Wiki

[Bryan Pendleton <bp...@gmail.com>]

> My motive in having a compact tutorial is that the user can have anoverview of what things one should need in succession(setting
> up environment, then running tests etc). I think Derby Getting started guide would also be a good place to add/modify these things.

I think your ideas and feedback are excellent; it is great to have
your experiences as it has been a while since any of the existing
developers has set their environment up from scratch :)

I think that we generally try to keep the external Derby
documentation, such as the Getting Started guide, focused on
the needs of the *users* of Derby, as opposed to the needs of
the *developers* of Derby. Our users are not expected to need
to learn how to compile Derby, run the tests, etc.

However, I think that your observations and improvements would
be great if you could edit them into the Derby developer's wiki
pages, starting probably somewhere around here:
http://wiki.apache.org/db-derby/DerbyDev

The wiki pages can be (and should be) edited by any member of
the Derby community, so please feel free to create a wiki account
for yourself and add your fixes, ideas, checklists, and tutorials
to those wiki pages so that future developers can benefit from them!

thanks,

bryan