Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: <derby-dev@db.apache.org>
Message-ID: <32280961.1181691506477.JavaMail.jira@brutus>
Date: Tue, 12 Jun 2007 16:38:26 -0700 (PDT)
From: "Laura Stewart (JIRA)" <jira@apache.org>
To: derby-dev@db.apache.org
Subject: [jira] Commented: (DERBY-2390) DOCS - Merge Working with Derby and
 Getting Started Guide
In-Reply-To: <6565599.1172777150695.JavaMail.jira@brutus>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable


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

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 simp=
ly summarize relevant points based on your decisions about the suggestions.=
  The document looks good but I think it would be clearer to novice users t=
o provide the following information / clarifications (in not particular ord=
er):

1) It looks like Kim has flagged the references to JDK 1.3 which is no long=
er 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 & CD=
C/Foundation 1.1 for J2ME. (Removes support for JDK 1.3 and J2ME/CDC/Founda=
tion 1.0)   -> DERBY-1982=20

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 suggesti=
on: "Deployment options - Here, probably, is where "Network Server" needs t=
o be defined."   IMHO the Deployment options section of the Getting Started=
 Guide has never been right.  The GS should only introduce the two basic op=
tions: Embedded and Server / Network Server.  Any more gets you into the de=
ep weeds really quickly.  Here's a basic 'Getting Started' replacement for =
this section:

=3D=3D=3D=3D  Begin of Replacement =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D
Before you install Derby, you should understand the system requirements and=
 two basic
frameworks provided.

=09Basic Frameworks Provided

The Derby software distribution provides two basic frameworks (also referre=
d 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 m=
achine (JVM) as the application.  Derby can be almost invisible to the end =
user because it is started and stopped by the application and often require=
s no administration.

 o Server (or Server based) is used to refer to Derby being started by an a=
pplication 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 o=
rder to access the database(s).  The Derby Network Server is part of the De=
rby software distribution and provides this type of framework for Derby.  D=
erby also works well with other, independently developed Server application=
s. =20

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D  END =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

o) The document would benefit from clarifying the three different 'command =
styles' shown in the 'Using the Derby tools and setup utilities'.  Adding i=
nformation to the 'Choose a method to run the Derby tools and startup utili=
ties' 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=20

Replace Method:
Run the tools using the jar files that are located in the directory where t=
he 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' sect=
ion of the table]
There are several ways that you can run the Derby tools and startup utiliti=
es.
  with:
 This section discusses how to setup the system environment variables neede=
d to run the Derby tools and utilities presented in the next section.  Thre=
e ways to run each tools and utilities are shown.  Choose the method that b=
est fits your own personal needs and interests.  Java programmers will prob=
ably 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 th=
e 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: '...usin=
g 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 w=
hich is right for you. =20

In the first table itself, the second row (derbyrun) remove the following:
  Col 2:  =E2=80=A2 Do not run the tools often  - (this is not a good recom=
mendation, see text above)
  Col 3: JAVA_HOME  - ( with JAVA in your PATH there is no reason to have J=
AVA_HOME set)

--- I hope you find this helpful.  I think these changes, though somewhat l=
ongish, will provide the intro needed to guide new users through the rest o=
f the document.  I will provide additional input tomorrow but I think this =
is the bulk of it. =20


> 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 Get=
ting Started Guide should=20
> be moved to the Reference Manual.

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