db-derby-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stanley Bradbury <Stan.Bradb...@gmail.com>
Subject Re: [WWD] Feedback requested on Chapters 1 and 2 of Working With Derby
Date Tue, 21 Feb 2006 22:31:21 GMT
Daniel John Debrunner wrote:

>Stanley Bradbury wrote:
>
>  
>
>>Please participate in the review of the  first two chapters of the
>>Working With Derby document.  The HTML files can be downloaded for
>>review from DERBY-913 using the URL:
>>    
>>
>
>These first two chapters seems like a clone of the getting starting
>guide to me, at least along the same approach. Therefore I'm not sure
>how this is making it easier for people to start using Derby.
>
>I'll repeat my earlier comments that I wonder if there's a better
>approach, aimed at having "activity 1" getting the user running SQL in
>less than three pages, rather than taking seven pages to running sysinfo.
>
>I'd like an approach of peeling the layers away, start simple with a
>single configuration, get that working, then move onto others.
>
>Your activity 1 dances around configurations, saying there are several
>but not going down any single path. Then I'm left on this page:
>
>file:///C:/temp/WWDhtml0220/cwwddinstalclspath.html
>
>with three setup scripts, do I run all, one only, or what? To someone
>who does not know Java, databases and/or Derby I think this is confusing.
>
>Then the last page
>
>file:///C:/temp/WWDhtml0220/cwwdverifyderby.html
>
>is meant to verify my setup, but the instructions state
>
>"... displays the information that describes (to the trained eye) the
>configuration of the Derby ..."
>
>but I'm not a "trained eye", I'm a newcomer, how does this page help me
>verify my setup and correct configuration.
>
>I think if you focussed on complete novices then one approach would be
>to hide the Java, classpath, configurations stuff as much as possible at
>first, and instead work out how to get to the ij> prompt as soon as
>possible.
>
>Ideally it would be:
>
> 1) You've just installed Derby, now start the SQL command line
>processor ij.
>
>  c:\> ij
>
> 2) Execute this command to create a database
>
>   ij> connect 'mydb;create=true';
>
> 3) Create a table
>   ij> create table etc. etc.
>
>
>Once the activities have worked through some SQL examples etc, you can
>then expand into what is happening behind the scenes, that it's
>embedded, where the database is, what the class path is and what it
>means, what ij is doing in terms of JDBC, etc. etc.
>
>Another starting point would be for the person used to client/server, a
>more natural start for them would be to have a start server command, and
>then get into ij, don't even mention embedded, or jar files.
>
>   1) You've just installed Derby, now start the database server
>       don't worry about details, we'll explain those later
>
>     c:\> java -jar lib\derbynet.jar start
>
>   2) Now start the command line processor
>
>     c:\> ij
>
>   3) Create a database on the server
>
>      ij> connect '//localhost/mydb;create=true';
>
>
>    etc. etc.
>
>
>An aside - ij is described as 'Derby's interactive JDBC scripting tool.
>ij has a set of commands that provide JDBC processing capabilities and
>also supports execution of SQL commands.' which is based upon its
>Javadoc. I realised over the weekend when I was looking at the javadoc
>that this is a really bad description of the tool, and has been for a
>long long time. ij's primary purpose is a command line processor for
>*SQL*, describing it as a *JDBC* scripting tool is just confusing for
>folks used to other databases that have SQL command line processors.
>
>Thanks for working on this Stan, but I really do believe that a
>different approach is needed compared to existing approach taken by the
>Getting Starting guide (that's been around for eight+ years).
>
>To repeat my earlier concern, if getting to the first query is hard, we
>will lose most of the newcomers in these early setup steps, the first 2%
>of such a tutorial is probably the most important.
>
>Dan.
>
>
>  
>
Hi Dan -
Thanks for your feedback.  You are absolutely right that these first two 
chapters are Getting Started Guide subjects and contain much to much 
reference information for a quick start document.  I will abbreviate the 
chapters to get the new user more quickly to SYSINFO and on to the meat 
of the activities (Ch 3-7).


Mime
View raw message