db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Stan Bradbury (JIRA)" <derby-...@db.apache.org>
Subject [jira] Commented: (DERBY-1394) Working With Derby - Introduction and prerequisites - Improvements
Date Fri, 16 Jun 2006 19:53:30 GMT
    [ http://issues.apache.org/jira/browse/DERBY-1394?page=comments#action_12416577 ] 

Stan Bradbury commented on DERBY-1394:
--------------------------------------

Thanks, Halley, for all the attention you are giving to improving Working With Derby. 
I like your suggestions and think we should go ahead and commit them with possibly a couple
of minor adjusts (aka tweaks) as listed below.
I'm new to the whole commit and patch process so am uncertain how best to proceed since you
have created patches for the issues already.  I assume (I would appreciate a confirmation
from a commiter) that I could create another patch that performs these 'tweaks' assuming no
one opposes them?

Comments and 'tweaks' on items in the Description.

#1 -  Needs to be "section"

#2 - "referred to as DERBY_HOME"
NOTE: at the time of writing it was (and still is) my understanding that DERBY_HOME will be
replacing DERBY_INSTALL throughout the v 10.3 manuals.
I wanted to introduce this term early in the document and originally worded it "referred to
as DERBY_HOME throughout the manual set".   In review this was identified as cumbersome and
removed.  Your rewrite is an improvement over the current wording.  Do you think something
like this might highlight the term even better?:

Note the filesystem path to the Derby installation (this is commonly referred to as DERBY_HOME
in the Derby documentation).  Either wording will be a improvement.

#3  - Commas
Many commas were overlooked, the text is much more readable with them.  The only added commas
that seem odd to me (and I am not studied in English grammar) are the commas before the lead-in
words 'because' and 'that'.  Do you know if this is grammatically correct?  When speaking
I do not normally pause at these points.

..Java database, that can be tightly embedded ...
..relational database engine, that is written and implemented ...
..different from what is shown here, because the java -version command...

#4 - Clarifying the download files and unbundling
I like the rewrite:

>From the Download page use the link to the 'Latest Official Release', then locate the
bin distribution (e.g. db-derby-10.1.2.1-bin.zip and db-derby-10.1.2.1-bin.tar.gz). Download
the appropriate file for your platform, '-bin.zip' for Windows or '-bin.tar.gz' for Unix/Linux",
and unzip/untar this file.
-- Perhaps changes to the versions referenced would also be helpful.  I was hesitant to list
a filename that would change from release to release (I am not sure there is a naming convention
in place for these files).  I also realize the document should probably use the likely v10.3
filenames (not 10.1.2.1).  Do you think it would be better to abstract the example names with
something like "db-derby-<version>-bin.tar.gz"?

I think it best to avoid touching on 'installation' details.  The assumption is that Derby
is already installed and the intent of this paragraph is to help the user locate the proper
file if, for some reason, they do not know where Derby is installed on the machine.  Installation,
though simple, can be a topic unto itself and the exact commands differ depending on the OS.
I think it best to let people turn to the installation information bundled with the download.
 If you decide to keep this sentence please change '..the filesystem path choosed..' to '..the
filesystem path choosen..'.

After decompressing the downloaded file, move the directory created to the filesystem path
choosed to be the root directory of the Derby installation (e.g., move db-derby-10.1.2.1-bin
C:\Derby) 

==== 
And the suggested rewrite of the 'Welcome ..' paragraph (comment dated Jun 14) is GREAT !!
 Thanks again for applying your talents to improving this document.


> Working With Derby - Introduction and prerequisites - Improvements
> ------------------------------------------------------------------
>
>          Key: DERBY-1394
>          URL: http://issues.apache.org/jira/browse/DERBY-1394
>      Project: Derby
>         Type: Improvement

>   Components: Documentation
>     Versions: 10.2.0.0
>  Environment: DITA-sourced documentation
>     Reporter: Halley Pacheco de Oliveira
>     Priority: Minor
>      Fix For: 10.2.0.0
>  Attachments: twwdIntro.diff, twwdIntro.diff.html, twwdIntro.html, twwdIntro_2.diff,
twwdIntro_2.diff.html, twwdIntro_2.html
>
> 1) There is a gramatical error:
> It's written "sections" and not "section":
> "In way of introduction this sections provides a brief description of Derby."
> and should be, in my opinion:
> "In way of introduction this section provides a brief description of Derby."
> 2) DERBY_HOME
> It's written:
> "Note the filesystem path to the Derby installation (referred to as DERBY_HOME)."
> but DERBY_HOME doesn't appear anywhere else in this page, so it is not possible
> to note it in this page. It only appears in the activities pages. By this reason,
> in my opinion, the sentence should be:
> "Note the filesystem path to the Derby installation (referred to as DERBY_HOME) in the
activities sections."
> 3) Commas could be used to make some sentences shorter:
> ===
> - "Derby is a full featured, open source relational database engine that is written and
implemented completely in Java."
> into
> + "Derby is a full featured, open source, relational database engine, that is written
and implemented completely in Java."
> ===
> - "It provides users with a small footprint, standards-based Java database that can be
tightly embedded into any Java based solution."
> into
> + "It provides users with a small footprint, standards-based, Java database, that can
be tightly embedded into any Java based solution."
> ===
> - "In it's default configuration there is no separate database server to be installed
or maintained by the end user."
> into
> + "In it's default configuration, there is no separate database server to be installed
or maintained by the end user."
> ===
> - "This document demonstrates but does not teach the Java, JDBC and SQL presented so
readers wishing a deeper understanding of these topics will need additional reference materials."
> into
> + "This document demonstrates, but does not teach, the Java, JDBC and SQL presented,
so readers wishing a deeper understanding of these topics will need additional reference materials.
> ===
> - "If unsure about the Java or Derby environments installed perform the following steps
before attempting the subsequent activities:"
> into
> + "If unsure about the Java or Derby environments installed, perform the following steps
before attempting the subsequent activities:"
> ===
> - "The output you see may be different from what is shown here because the java -version
command outputs vendor-specific information."
> into
> + "The output you see may be different from what is shown here, because the java -version
command outputs vendor-specific information."
> ===
> - "If the command produced an error or the version listed is not 1.3 or higher please
install a Java development kit before continuing."
> into
> + "If the command produced an error or the version listed is not 1.3 or higher, please
install a Java development kit before continuing."
> ===
> - "From the Downloads page use the link to the 'Latest Official Release' then locate
the bin distribution (e.g. db-derby-10.2.0-bin). Download the file and unbundle the release."
> into
> + "From the Download page use the link to the 'Latest Official Release', then locate
the bin distribution (e.g. db-derby-10.2.0-bin). Download the file and unbundle the release."
> 4) Download the file and unbundle the release.
> Is is not easy to understand what this sentence means. There are two files for the binary
distribution: -bin.zip and -bin.tar.gz
> So the previous sentence could be changed to:
> "From the Download page use the link to the 'Latest Official Release', then locate the
bin distribution (e.g. db-derby-10.1.2.1-bin.zip and db-derby-10.1.2.1-bin.tar.gz). Download
the appropriate file for your platform, '-bin.zip' for Windows or '-bin.tar.gz' for Unix/Linux",
and unzip/untar this file. After decompressing the downloaded file, move the directory created
to the filesystem path choosed to be the root directory of the Derby installation (e.g., move
db-derby-10.1.2.1-bin C:\Derby)

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


Mime
View raw message