The Getting Started Guide is incomplete (section: Installing and working with
Derby) and so not helpful to new users
--------------------------------------------------------------------------------------------------------------------
Key: DERBY-879
URL: http://issues.apache.org/jira/browse/DERBY-879
Project: Derby
Type: Bug
Components: Documentation
Reporter: Stan Bradbury
The "Installing and working with Derby" chapter of the Getting Started Guide is
incomplete and so not useful to a new Derby user (see user feedback attached in
the comments). This entry contains documents for each section (html page) of
this Chapter what needs to be changed (marked PROBLEM) and things that would be
helpful to add (ENHANCEMENT). The items marked PROBLEM should be addressed
ASAP.
Chapter "Installing and working with Derby" - First page
>> http://db.apache.org/derby/docs/dev/getstart/cgsinsta.html
Describes the sections in the Chapter. Update as necessary to reflect changes
in section titles and order.
SECTION: Installing Derby
>> http://db.apache.org/derby/docs/dev/getstart/cgsinstallingderby.html
No major problems
ENHANCEMENT: example showing the naming convention of a bin archive is needed.
SECTION: Setting up your Java environment
>> http://db.apache.org/derby/docs/dev/getstart/tgssetupjavaenvir.html
OK if java is setup properly in the PATH.
PROBLEM: Command examples need to be added to Item 2 to resolve problems with
the PATH.
PROBLEM: The problem of not having a JDK installed is not covered.
PROBLEM: Under Related Topics - remove the link to: "Manually setting
environment variables and paths"
SECTION:Using the tools and startup utilities
>> http://db.apache.org/derby/docs/dev/getstart/cgsusingtoolsutils.html
This is not a Getting Started subject. Reduce the scope of this to IJ and
SYSINFO
PROBLEM: Title is not accurate
PROBLEM: dblook, export/import, database class utilities are not Getting
Started Topics - remove references
PROBLEM: the scripts listed require DERBY_INSTALL be set in order to work as
shown in the following sections
PROBLEM: /frameworks/embedded/bin is not a valid directory (need DERBY_INSTALL)
PROBLEM: Only setting PATH for UNIX is identified - this is required for
WINDOWS in order for the scripts to work as shown in the following sections
PROBLEM: the /bin directory does not exist, be explicit
(DERBY_INSTAALL/frameworks/embedded/bin)
SECTION: Using sysinfo
>> http://db.apache.org/derby/docs/dev/getstart/cgsusingsysinfo.html
PROBLEM: In the standard distribution of Derby (the 'bin' distribution) the
script DOES NOT set the appropriate environment as stated on this page.
ENHANCEMENT: An example and explanation of the output is needed.
SECTION: Running ij
>> http://db.apache.org/derby/docs/dev/getstart/tgsrunningij.html
PROBLEM: In the standard distribution of Derby (the 'bin' distribution) the
script DOES NOT set the appropriate environment as stated on this page.
PROBLEM: Incorrect statement: "You must include the /bin directory in your PATH
environment variable to run ij." This refers to running the IJ script.
ENHANCEMENT: An example of a simple select is needed.
ENHANCEMENT: State that the command will not execute until a semicolon is
typed.
SECTION: Manually setting environment variables and paths
>> http://db.apache.org/derby/docs/dev/getstart/cgsmanuallysetting.html
PROBLEM: DERBY_INSTALL and CLASSPATH are key variables and should be discussed
before SYSINFO and IJ.
PROBLEM: This statement is very confusing: "This document assumes that
directory is named Derby_10" . Also it is not good to use a version number
here, what about the next release?
PROBLEM: This is incorrect: "The classpath is a list of the class libraries
needed by the JVM " reword as something like 'libraries available to' or 'known
to' or something.
ENHANCEMENT: Introduce NoClassDefFoundError exception here
ENHANCEMENT: Better title needed
SECTION: Set the DERBY_INSTALL environment variable
>> http://db.apache.org/derby/docs/dev/getstart/tgs36360.html
PROBLEM: /frameworks/embedded/bin does not exist (need DERBY_INSTALL).
PROBLEM: Unix command example not provided to set variable
ENHANCEMENT: use full path names for directories (e.g. C:\Derby_10)
SECTION: Set the classpath
>> http://db.apache.org/derby/docs/dev/getstart/tgs26250.html
PROBLEM: This is incorrect: "The classpath is a list of the class libraries
needed by the JVM " reword as something like 'libraries available to' or 'known
to' or something.
PROBLEM: /frameworks/embedded/bin directory and /frameworks/NetworkServer/bin
do not exist (need DERBY_INSTALL).
PROBLEM: Unix command example not provided to set variable
PROBLEM: Though nice, the bullets about manually running SYSINFO and IJ are not
tied into the topic of CLASSPATH.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
