db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Laura Stewart (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-2390) DOCS - Merge Working with Derby and Getting Started Guide
Date Tue, 12 Jun 2007 23:38:26 GMT

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

Laura Stewart commented on DERBY-2390:
--------------------------------------

Comments made by Stan Bradbury on derby-dev 5/30/2007

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 somewhat 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.  



> 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
>            Assignee: 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