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] Chap 1 and 2 (v 1.1) submitted for review
Date Tue, 07 Mar 2006 20:25:18 GMT
Responses to each point in line, first line preceded w/  >>>
Jean T. Anderson wrote:

>Stanley Bradbury wrote:
>>I've submitted Chapters 1 and 2 of the Work With Derby [WWD] document
>>for feedback.  These sections are based on the version 1.1 proposal
>>submitted last week.  You can download the formatted PDF document for
>>review and comment using the following URL.
>You're making excellent progress! I put a few notes below with stuff I
>noticed off the top.
>>I am also asking for feed back in the following areas (support for or
>>alternatives to) :
>>2) Referencing the Derby installation file path.  I see setting and
>>using the environment variable DERBY_HOME (currently called
>>DERBY_INSTALL) to indicate the filesystem path to the DERBY installation
>>as the best way to provide command syntax examples (e.g.   java -jar
>>$DERBY_HOME/derbytools.jar ij)
>>With the changes made by DERBY-1019 is one of the few 'setup' steps that
>>remain before launching into IJ.
>>Is there a better way?
>(1) Since #2 in your point above mentions a concern about DERBY_HOME, I
>noticed that pdf page 5 (printed page 3) mentions DERBY_HOME, but the
>next page actually defines and shows how to set it. I wonder if that
>first mention on page 5 could be removed, delaying it a page.
 >>> Outside to the context the issue I raised (#2), is listing the term 
there distracting or unclear?  I placed it there because the term 
DERBY_HOME (currently DERBY_INSTALL) is used through out the descriptive 
text of the Derby documentation.  I wanted to introduce this in the WWD 
'Introduction' so that people who might jump into the documentation from 
WWD would have seen the term.  Also, though I do not explicitly state 
this (I think it would detract from the flow) the two forms used in WWD 
, italicized (printed page 4) and block-letter (printed page 3), 
represent different things.  Italicized DERBY_HOME in body-text refers 
to the filepath to the Derby installation represented as an environment 
variable - these references would be removed if a better alternative is 
presented.   DERBY_HOME in block-letters is another way of witting 'the 
DERBY installation directory or folder'.  I had  planned to leave the 
reference in the Introduction (numbered page 3) regardless of whether 
the variable DERBY_HOME (italics) ends up being set and used in the 
command examples. 

>(2) Also I wonder if this phrase about posting to derby-user on pdf page
>5 should be removed:
>  A response is typically received within a few hours....
>Realistically we can't guarantee such a quick response, especially
>considering time zones around the world, and it might be better to not
>raise expectations.
 >>> I agree it is best not to set such expectations (though the list if 
very good about this, I feel).  I will remove the response time phrase.

>(3) pdf page 6 (printed page 4) says "preform" when I think "perform"
>was meant:
>  "The commands in this Activity Sequence preform the following operations:"
>  "6. Preform a qualified select of the record with column ID=20"
 >>> Will correct this.

>(4) pdf page 6 (printed page 4), step 8 shows the "shutdown=true"
>command. Since Activity 1 shows embedded use and "exit" in an embedded
>environment automatically performs that shutdown=true
>(http://db.apache.org/derby/docs/dev/tools/rtoolsijcomref33358.html), I
>wonder if you could delay showing that syntax and the error that gets
>produced until the next activity with the client driver.
 >>> You are correct that this could be introduced in activity 3 (JDBC 
with the embedded driver). There are two reasons I chose to place the 
topic here:
1) It is a counter point to the item in the 'Summary' of the next 
activity,  outline point:
   >>  Best practice - shutdown the server do not shutdown the database 
from a client
2) I believe that introducing concepts a few at a time across the 
activities is better than creating a 'dense' topic by lumping everything 
into one activity (in this case Activity3).
 >>> I am leaning towards deferring introducing 'shutdown' until 
Activity 3 since IJ does properly automate the process.  The recent 
revision of WWD does take advantage of the automations provided by 
derbygo.jar and IJ.  I would like to hear some other opinions on this if 
we are to keep the document as-is.

>again, excellent progress!

View raw message