Kim Haase (JIRA) wrote:
[ 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.
= = = = SNIP === Stan's comments:
Hi Laura -
I'm posting these comments to the email thread but NOT adding a comment
to the JIRA issue. You can add this message to DERBY-2390 if you like
or simply summarize relevant points based on your decisions about the
suggestions. The document looks good but I think it would be clearer to
novice users to provide the following information / clarifications (in
not particular order):
1) It looks like Kim has flagged the references to JDK 1.3 which is no
longer supported in this release. The info from the WIKI states:
10.3 Platforms : Minimum JDK support will change to JDK 1.4.2 for J2SE &
CDC/Foundation 1.1 for J2ME. (Removes support for JDK 1.3 and
J2ME/CDC/Foundation 1.0) -> DERBY-1982
o) Laura is correct raising issue 6: "I don't think that we do a good
job of describing what the Network Server is." And I agree with Kim's
suggestion: "Deployment options - Here, probably, is where "Network
Server" needs to be defined." IMHO the Deployment options section of
the Getting Started Guide has never been right. The GS should only
introduce the two basic options: Embedded and Server / Network Server.
Any more gets you into the deep weeds really quickly. Here's a basic
'Getting Started' replacement for this section:
==== Begin of Replacement ===============
Before you install Derby, you should understand the system requirements
and two basic
frameworks provided.
Basic Frameworks Provided
The Derby software distribution provides two basic frameworks (also
referred to as 'deployment options'). The simple embedded framework and
the Derby Network Server framework.
o Embedded is used to refer to Derby being started by a simple
single-user Java application. In this framework Derby runs in the same
Java virtual machine (JVM) as the application. Derby can be almost
invisible to the end user because it is started and stopped by the
application and often requires no administration.
o Server (or Server based) is used to refer to Derby being started by
an application that provides multi-user connectivity to Derby across a
network. In this framework Derby runs in the Java virtual machine (JVM)
that hosts the Server and applications connect to the Server from
different JVMs in order to access the database(s). The Derby Network
Server is part of the Derby software distribution and provides this type
of framework for Derby. Derby also works well with other, independently
developed Server applications.
========== END =============
o) The document would benefit from clarifying the three different
'command styles' shown in the 'Using the Derby tools and setup
utilities'. Adding information to the 'Choose a method to run the Derby
tools and startup utilities' seems like where this is needed. Also, for
clarity and use the text provided below you will need to perform the
following global changes on two of the three 'Method' columns in each table:
Replace Method:
Run the tools as standalone commands
with:
Run the tools using the command scripts
Replace Method:
Run the tools using the jar files that are located in the directory
where the tools reside.
with:
Run the tools using the derbyrun.jar archive
Intro Replacement suggestion [NOTE: you could instead add the three
'People/Programmers ... interested/have' sentences below to the 'When to
Use' section of the table]
There are several ways that you can run the Derby tools and startup
utilities.
with:
This section discusses how to setup the system environment variables
needed to run the Derby tools and utilities presented in the next
section. Three ways to run each tools and utilities are shown. Choose
the method that best fits your own personal needs and interests. Java
programmers will probably be interested in learning the full command
syntax show by the methods: '...using java command'. People who have a
full Derby 'bin' distribution available, want to do a minimal amount of
typing when running the tools and don't mind setting up a few
environment variables upfront will like using the method '...shell
scripts provided'. People interested in performing the minimum amount
of environment setup and being able to run the tools when only the derby
jarfiles are available will want to use the method: '...using the
derbyrun.jar archive'.
Replace:
Choose the method that you want to use:Choose the method that you want
to use:
with:
Use the following table to identify the setting required for the
method which is right for you.
In the first table itself, the second row (derbyrun) remove the following:
Col 2: • Do not run the tools often - (this is not a good
recommendation, see text above)
Col 3: JAVA_HOME - ( with JAVA in your PATH there is no reason to
have JAVA_HOME set)
--- I hope you find this helpful. I think these changes, though
longish, will provide the intro needed to guide new users through the
rest of the document. I will provide additional input tomorrow but I
think this is the bulk of it.
