db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-2390) DOCS - Merge Working with Derby and Getting Started Guide
Date Thu, 24 May 2007 18:11:16 GMT

    [ https://issues.apache.org/jira/browse/DERBY-2390?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12498750
] 

Kim Haase commented on DERBY-2390:
----------------------------------

This is a terrific job, Laura -- I think you've done a great job merging the manuals. These
comments are on the individual sections. I don't think these answer every question you had,
though. Let me see -- question 5 -- I think it would be good to update the output to 10.3
if possible, but getting the svn version right is probably not possible since code hasn't
frozen. Question 7 -- I believe both "mode" and "environment" are used but in slightly different
situations -- it might be worth adding the mention of "mode" to the Terminology section? I
think "configuration" is used only in "Deployment options" -- not sure.


Introduction to Derby

Nice synthesis.

Last sentence -- you might reverse the order of "system requirements and deployment options"
to make it the same order as the sections that follow.


Deployment options

Here, probably, is where "Network Server" needs to be defined. But even the Admin Guide doesn't
seem to define it exactly. It talks about what it *does* but doesn't say what it *is*. I don't
know the answer to that question.


System requirements

I think for 10.3 the JDK version is 1.4 or higher? Maybe you were figuring on dealing with
this stuff later.


Product documentation for Derby

Glad you changed this from "library" -- that's a confusing term in software!

Getting Started introduces dblook as well as sysinfo and ij, I think -- at least briefly?

The last paragraph mentions "Version 10.2" -- is that from one of the conrefs that need to
be changed for the next release?


Installing Derby

I like the reordering here.


Setting up your environment

In step 2, the common usage is "Set the environment variables", not "Set up".


Choosing a method to run the Derby tools and startup utilities

A table works really well here! 

First row, middle column: second sentence repeats content of first column so may be removable.

Third row, first column: should be "the java command", I think.

Third column: in both the second and third rows, the last paragraph is in bigger type than
the other(s) in the PDF. Any idea why? I see this happens in other tables; it may just be
a quirk of the DITA tools...

Also, in the third row, shouldn't CLASSPATH be included in the list of environment variables
to set?


Syntax for the derbyrun.jar file

I'm wondering if this section shouldn't come after the next one (Setting the environment variables).
The information is less basic. 

Also, I think the first sentence should be more general because we're not talking just about
the CLASSPATH here. Maybe "If you use the derbyrun.jar file, you do not need to remember which
jar file to use for a particular purpose (as described in Libraries provided by Derby)."


Setting the environment variables

Second sentence: The common usage is that you set an environment variable, not set it up.

Step 1: I wonder why DERBY_10 is in code font in the second occurrence in the sentence but
not in the first?

Step 2: Is there some reason why one command looks in the bin directory and the other just
in the main DERBY_HOME directory? It is less distracting if they are the same.

Step 3: I think you need a "the" in the Windows entry ("add the JAVA_HOME environment variable").


Also you might use a more recent version of the 1.4.2 SDK -- the current version is j2sdk1.4.2_14.
(By default it installs as j2sdk, not j2se.) Or even (gasp!) 1.5, the current version of which
is jdk1.5.0_11. (They changed the naming convention for 1.5.) We previously used the version
one up from the minimum -- we might continue that. Not necessary if it's too much work.

The Note here is a bit confusing. The thing is, if you have a Java executable in your path,
that almost invariably means that you have set JAVA_HOME previously (and then set your PATH
to include $JAVA_HOME/bin). So the note is in effect saying, "If you have already set JAVA_HOME,
you don't need to set JAVA_HOME", which pretty much goes without saying. People who have JAVA_HOME
set will know that and will skip the step anyway. So you could remove the note, I think. 

Possibly what really needs to be here is something about adding $JAVA_HOME/bin to your PATH
and using java -version to verify that it's set correctly. (See discussion later about "Verifying
the Derby system configuration".)

Step 4: In the sentence about the control panel, there should not be a semicolon after "bin".

Step 5: I don't think you need the second "the" (before JAVA_HOME).

I think in the Note "very" should be "verify"?

In the second paragraph after that, "follow" should be "following".


Using the Derby tools and startup utilities

I think it is not quite accurate to say that "These scripts also help you set up your CLASSPATH
environment variable." The scripts that start the Derby tools set the CLASSPATH variable while
they are being run, but they don't leave it set. It would be better to leave out the sentence,
I think.

There are additional scripts in the bin directory that can be used to set the classpath (setEmbeddedCP,
etc.). I think they all work fine if DERBY_HOME is set. I don't know if they need to be mentioned
at this point.

Running sysinfo, etc.

I notice the language on running the commands is not exactly parallel in all three sections
(sysinfo, ij, dblook) -- you might look closely at these and sync them up.

I notice the first sentence in the second table row about sysinfo actually mentions dblook
-- cut/paste error apparently.

I'm glad you added dblook to this -- it was missing before, for some reason.

There is a bullet under "Running sysinfo", after "To run the sysinfo script" -- but there
is only one bullet item, so maybe the two sentences should be merged into "Choose the method
for running the sysinfo script that you want to use", or something like that. Similarly, there
is a "1." in front of a sentence under dblook, but this is the only item in the numbered list
-- so it should probably be a plain paragraph, similar to whatever you use for sysinfo. (With
ij there are actually three bullet items so there is no problem there.)

In the sentence above that there is a minor parallel-structure glitch -- should be either


"to either a console or a file"

or

"either to a console or to a file"


Manually setting the CLASSPATH environment variable

See what Stan says about this, but we might want to de-emphasize these scripts. Using derbyrun.jar
simplifies matters considerably -- not only do you not need to figure out which classpath
script to run, you don't need to set the classpath at all.


Verifying the Derby system configuration

Another JDK 1.3 mention.

Hm, there's a mention of using java -version back under System Requirements, but that was
before all the info about setting JAVA_HOME -- I wondered about that. But I think most of
the material in this current section is redundant at this point? The "echo DERBY_HOME" material
is under "Setting the environment variables". In order for "java -version" to work, $JAVA_HOME/bin
has to be in your PATH, just as $DERBY_HOME/bin has to be in your path in order for the standalone
commands to work. So maybe that should be in the earlier section about setting environment
variables. 

You do have at least one xref to this section that would need changing...


Self-study tutorial for users new to Derby

Under "Tutorial skills and software requirements," you might want to change "run" to "use"
in the second sentence. (You run commands, but you don't run syntax.)

Another JDK 1.3 mention (and Derby 10.2).

Under "Problems and feedback on the tutorial activities" maybe "even more useful" should be
changed to "more useful" -- seems a bit presumptuous otherwise. I missed this one before.


Activity 1

The way you reorganized this is excellent.


Creating a directory and copying scripts into the directory

Step 1: I would suggest that you should NOT change to the directory where you installed Derby.
It's not a great idea to add stuff to a Derby installation. The DERBYTUTOR directory should
be in your home directory or some other place where you do your work.

Step 4: Period missing after second sentence.

Remove the sentence "In the following examples, substitute the correct path for the DERBY_HOME
variable:". In fact, if you have the DERBY_HOME variable set, you can use exactly the commands
shown, and it saves typing. (No need to put DERBY_HOME in italics.)

Also, at the end of this step I would recommend adding the "Important" note from Step 1 of
Activity 3, since it applies here as well.


Creating a Derby database and running SQL statements

Step 7a: Missing period at end.


Activity 2: Run SQL using the client driver

Step 2: We should use derbyrun.jar here, I think. Replace

derbynet.jar start

with

derbyrun.jar server start

Step 4: "java" could be in code font in the third sentence.

Step 11: Replace

derbynet.jar shutdown

with

derbyrun.jar server shutdown


Activity 4

Steps 2 and 4 -- replace derbynet.jar with derbyrun.jar as in Activity 2.

Step 3: I think you can replace derbyclient.jar with derbyrun.jar -- but check with Stan on
this.

For the Activity notes at the end, you might want to check with Rick Hillegas to see if this
needs any updating to reflect the security changes for this release.


Database connection URL

There's some inconsistency in how the syntax is specified -- server and port are in angle
brackets, but databaseName and URLAttributes are in italics. Since they are all meant to be
replaceable items, they should all be in the same format (italics, I think) -- unless there's
something I'm not understanding.


Typographical conventions

Were we going to try to update these so that people would use the correct conventions going
forward? You have used our proposed doc conventions for this book, at least. Or is this an
item for later when we have time to actually make corresponding changes to the other docs?
(Maybe we could update one item at a time, say starting with fixed width for file and directory
names.) 


Libraries provided by Derby

First sentence: I think "their functions" would be more correct.

The format of this table seems confusing but I am not sure how to fix it; maybe it needs to
be a 3-column table, "Library", "Library file name(s)", "Use"?


Libraries not provided by Derby

Looks like this can be cut now, since it relates to JDK 1.3.


Scripts included with Derby

The sentence introducing the list should be changed from 

The complete list of scripts that are included with Derby are:

to 

The complete list of scripts that are included with Derby is:



> DOCS - Merge Working with Derby and Getting Started Guide
> ---------------------------------------------------------
>
>                 Key: DERBY-2390
>                 URL: https://issues.apache.org/jira/browse/DERBY-2390
>             Project: Derby
>          Issue Type: Improvement
>          Components: Documentation
>            Reporter: Laura Stewart
>         Assigned To: Laura Stewart
>             Fix For: 10.3.0.0
>
>         Attachments: cgsintro.html, getstartderby.pdf, rgsdocs17307.html
>
>
> The activities in the Working with Derby guide should be merged into the Getting Started
Guide.
> Review Getting Started Guide for any reference info that should be either "shared" with
another guide
> or moved to another guide. For example, the SQL Syntax section in the Getting Started
Guide should 
> be moved to the Reference Manual.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.


Mime
View raw message