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 Fri, 10 Mar 2006 00:52:29 GMT
Hi David -

Thanks for the feedback.  My responses interspersed - >>> marks the 
beginning of each response.

David W. Van Couvering wrote:

> Thanks for your work on this, Stanley.  Here are some comments, 
> probably more to follow:
> - It would be nice to tell the user what each activity is and what 
> they can expect to be able to do and what they will learn as a result 
> of each activity.
 >>> I removed the chapter descriptions from this revision (v 1.1) based 
on initial responses to the more tutorial approach taken originally - it 
would be easy to add these back in (perhaps I removed too much in this 
revision}.  I will highlight this issue by placing it on what I am now 
calling my 'Request for Comments' list along with the other two items.  
I will solicit specific feedback on the items on this list later this 
month.  Unless I get strong  objections I will add this back in. 

> - Somehow this section isn't very welcoming.  It seems very 
> detail-oriented from the get-go.  Is there a way to make it a little 
> more conversational, such as "Welcome to Derby!  We think you'll find 
> Derby to be both easy to use and fully functional.  In this document 
> we hope to help you get up and running with Derby as quickly as 
> possible."
> Think of it as a really nice hotel with the friendly staff welcoming 
> you into to the hotel, or a very good maitre'd welcoming you into a 
> great restaurant.
 >>> Thank you for the specific rewording, unless you object I will add 
this text to the document.  Overall I plan for the activity sections to 
be terse and to the point but I see no reason the Introduction could not 
be conversational and inviting.  I will look at the reset of the section 
in that light as well.

> - You say "mkdir DERBYDBS" and then "cd DERBYDBS" and then "cp 
> something.sql .".  This makes no sense, as something.sql must be 
> somewhere else than within DERBYDBS.  What is the full path to 
> something .sql?
 >>> something.sql is my bad.  Everyone caught that - it is placeholder 
for the actual script that is yet be be named. All references will be 
updated when the script name and location is known.

> - 'Activity Sequence' is a bit jargony.  Rather than say "The commands 
> in this Activity Sequence perform the following operations" can't you 
> just say "The commands below accomplish the following tasks".  And 
> can't you just call it a "Task" rather than an "Activity Sequence"?
 >>> I chose Activity Sequence because Task sounds, well taxing, like 
doing the chores.  I am not wedded to the term 'Activity Sequence' but I 
do want to have one  succinct heading for each commands section in every 
chapter.  Originally it was Activity Command Sequence but that seemed 
too long.  I will look at using a different phase in the body of the 
text when referring to the section so it does not appear as much.   Are 
there any word-smiths out there with ideas on a different section 
heading and reference term to use in the body of the text?

> - I don't think you need the note about Windows and UNIX commands, 
> that will be quite obvious once the user gets into it
 >>> I agree - it looks even worse in the Chapter I am currently working 
on.  I will let the following statement in the Introduction be the only 
place this is stated:  " Complete command syntax is presented that will 
execute on a Windows machine or in a UNIX/Linux Korn shell. "

> - I am sure you'll fix the jar file name from derbygo.jar to 
> derbyrun.jar?
 >>> Yep.  I bet on the wrong horse with regard to which name would win out.

> - I thought you could just say 'java -jar derbyrun.jar ij' (at least, 
> that's how Andrew represented it in his email, maybe he was using 
> shorthand).
 >>> I will test this.  If it works (and I expect it will) then this 
shorter form  is the preferred syntax.

> - Can you use all caps for the JDBC URL?  Does 
> "JDBC:DERBY:FIRSTDB;CREATE=TRUE" really work?  I notice in your 
> comment at the end that you use lower-case, so it's inconsistent too.
 >>> Good get - I will correct this.  I got carried away with 
uppercasing all the SQL statements (upper case SQL seems to be a 
standard in the Derby docs).

> - In general I would think most people would type in lower-case, not 
> upper-case...  I would hate to force people to turn on caps-lock when 
> it's not needed.
 >>> Do you feel I should move away from using UPPERCASE in the SQL 
statements despite it's prevalence in the documentation?  I know that I 
don't enter sql in uppercase.

> Thanks, and I appreciate the incremental approach to reviewing this.
> David

View raw message