You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by Stanley Bradbury <St...@gmail.com> on 2006/04/24 16:56:21 UTC
[WWD] LAST CALL - for comments: CH 3 and 4 Revision 1.1 review
Please submit comments on Chapters 3 and 4 (rv 1.1) of Working With
Derby by the end of business today. I will be preparing a PATCH for
the commit of these chapters later today (along with some format updates
of Chapters 1 and 2).
Thanks
Review background and links included below for your convenience.
-------- Original Message --------
Subject: [WWD] CH 3 and 4 Revision 1.1 review
Date: Sun, 16 Apr 2006 09:58:07 -0700
From: Stanley Bradbury <st...@gmail.com>
To: derby-user@db.apache.org
I've attached the Review packet for the revision 1.1 of Ch 3 and 4 based
on the feedback received from the community. To view the revisions
download the file Review-WWD-Ch3-4rv1.1.zip (
http://issues.apache.org/jira/secure/attachment/12325379/Review-WWD-Ch3-4rv1.1.zip ). As
requested, more detail and code examples were added to Ch 4, section
2: :The WwdEmbedded program" (original draft ~750 word - rv1.1 ~1325
words). This section is not intended to teach JDBC and Java but rather
describe the basic steps to access data in a Derby database using the
embedded driver. Please let me know if this is adequate to describe the
program to a beginning level programmer that is not familiar with JAVA
or JDBC. If these drafts meet with general approval I hope to submit
them for checkin late this week.
=== SNIP ==
Re: [WWD] LAST CALL - for comments: CH 3 and 4 Revision 1.1 review
Posted by Stanley Bradbury <St...@gmail.com>.
John Embretsen wrote:
> Jean T. Anderson wrote:
>
>> Over all I think this looks pretty good, Stan. Here are a couple minor
>> suggestions. Page numbers referenced are the printed page.
>>
>> Page 5: Activity 2: "Activity miscellanea"
>>
>> I suggest simplifying this section title to something like "Activity
>> Notes" so users who aren't native to English won't feel compelled to
>> look "miscellanea" up in the dictionary.
>
>
> I agree...
>
>> Page 7: Activity 3: Step 2
>>
>> "verify that the Java SDK is proper installed" should be "verify that
>> the Java SDK is properly installed"
>
>
> This may be of microscopic importance at this point in time, but:
>
> To make this guide more in line with current naming conventions in the
> world of Java (and to reduce the need for maintenance), I suggest not
> using "Java SDK" at all. The reason for this is that as of J2SE 5.0
> (or 1.5 if you wish), the development kit has reverted back to the
> name "JDK" from "Java 2 SDK" (or "J2SDK"), and the runtime environment
> has reverted back to "JRE" from "J2RE".
> See http://java.sun.com/j2se/1.5.0/docs/relnotes/version-5.0.html for
> details.
>
> So perhaps "verify that the Java development kit is properly
> installed" is better/more general?
>
> By the way, more on Java SE/EE naming here:
> http://java.sun.com/developer/technicalArticles/JavaOne2005/naming.html
>
>
> Also on Page 7:
>
> Activity 3, step 1: There is a space missing in "set theCLASSPATH:"
>
>
-- And in addition Jean had stated:
Page 11: Activity 3: "Shutdown the Database"
Do you want to mention that nothing bad will happen if you don't
explicitly shutdown the database? and that Derby will run recovery code
on the next startup?
If I were a new user, I would read "The shutdown process puts the
database in a consistent state" and wonder if I would risk leaving the
database in an inconsistent state if I didn't explicitly shut it down.
= = = = =
Thank you Jean and John -
I will improve / correct these areas. I really appreciate the information on JDK vs SDK and move away from using either even though I do have a love for TLAs (Three Letter Acronyms).
I was indulging in a bit of whimsy when I selected the word
'miscellanea' and can see how that would not 'play' well to a global
audience (english as a second/third/.. language). I will avoid such
word-play in the future (and rename the section in Ch 3 that also
suffers from whimsy)..
Re: [WWD] LAST CALL - for comments: CH 3 and 4 Revision 1.1 review
Posted by John Embretsen <Jo...@Sun.COM>.
Jean T. Anderson wrote:
> Over all I think this looks pretty good, Stan. Here are a couple minor
> suggestions. Page numbers referenced are the printed page.
>
> Page 5: Activity 2: "Activity miscellanea"
>
> I suggest simplifying this section title to something like "Activity
> Notes" so users who aren't native to English won't feel compelled to
> look "miscellanea" up in the dictionary.
I agree...
> Page 7: Activity 3: Step 2
>
> "verify that the Java SDK is proper installed" should be "verify that
> the Java SDK is properly installed"
This may be of microscopic importance at this point in time, but:
To make this guide more in line with current naming conventions in the world of Java (and to reduce the need for maintenance), I suggest not using "Java SDK" at all. The reason for this is that as of
J2SE 5.0 (or 1.5 if you wish), the development kit has reverted back to the name "JDK" from "Java 2 SDK" (or "J2SDK"), and the runtime environment has reverted back to "JRE" from "J2RE".
See http://java.sun.com/j2se/1.5.0/docs/relnotes/version-5.0.html for details.
So perhaps "verify that the Java development kit is properly installed" is better/more general?
By the way, more on Java SE/EE naming here:
http://java.sun.com/developer/technicalArticles/JavaOne2005/naming.html
Also on Page 7:
Activity 3, step 1: There is a space missing in "set theCLASSPATH:"
--
John
Re: [WWD] LAST CALL - for comments: CH 3 and 4 Revision 1.1 review
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Over all I think this looks pretty good, Stan. Here are a couple minor
suggestions. Page numbers referenced are the printed page.
Page 5: Activity 2: "Activity miscellanea"
I suggest simplifying this section title to something like "Activity
Notes" so users who aren't native to English won't feel compelled to
look "miscellanea" up in the dictionary.
Page 7: Activity 3: Step 2
"verify that the Java SDK is proper installed" should be "verify that
the Java SDK is properly installed"
Page 11: Activity 3: "Shutdown the Database"
Do you want to mention that nothing bad will happen if you don't
explicitly shutdown the database? and that Derby will run recovery code
on the next startup?
If I were a new user, I would read "The shutdown process puts the
database in a consistent state" and wonder if I would risk leaving the
database in an inconsistent state if I didn't explicitly shut it down.
In other words, users don't have to worry if their program ends (or
crashes) before a shutdown is invoked.
by the way -- I like the sample app. It's cute.
-jean
Stanley Bradbury wrote:
> Please submit comments on Chapters 3 and 4 (rv 1.1) of Working With
> Derby by the end of business today. I will be preparing a PATCH for
> the commit of these chapters later today (along with some format updates
> of Chapters 1 and 2).
> Thanks
>
> Review background and links included below for your convenience.
> -------- Original Message --------
> Subject: [WWD] CH 3 and 4 Revision 1.1 review
> Date: Sun, 16 Apr 2006 09:58:07 -0700
> From: Stanley Bradbury <st...@gmail.com>
> To: derby-user@db.apache.org
>
>
>
>
> I've attached the Review packet for the revision 1.1 of Ch 3 and 4 based
> on the feedback received from the community. To view the revisions
> download the file Review-WWD-Ch3-4rv1.1.zip (
> http://issues.apache.org/jira/secure/attachment/12325379/Review-WWD-Ch3-4rv1.1.zip
> ). As requested, more detail and code examples were added to Ch 4,
> section 2: :The WwdEmbedded program" (original draft ~750 word - rv1.1
> ~1325 words). This section is not intended to teach JDBC and Java but
> rather describe the basic steps to access data in a Derby database using
> the embedded driver. Please let me know if this is adequate to describe
> the program to a beginning level programmer that is not familiar with
> JAVA or JDBC. If these drafts meet with general approval I hope to
> submit them for checkin late this week.
>
> === SNIP ==
>