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.
http://issues.apache.org/jira/secure/attachment/12323814/workingwithderby0306.pdf
...
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!
regards,
-jean
