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:
INTRODUCTION
- 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.
ACTIVITY 1
- 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.
CREATING THE DATABASE AND RUNNING SQL
- '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
