[ http://issues.apache.org/jira/browse/DERBY-1394?page=all ]
Halley Pacheco de Oliveira updated DERBY-1394:
----------------------------------------------
Attachment: twwdIntro_2.diff
twwdIntro_2.diff.html
twwdIntro_2.html
I would also like to modify the first paragraph of this page, shown bellow:
"Welcome to Derby! We think you'll find Derby to be an easy to use and fully
functional RDBMS. Through the activities in this document we hope to help you
get up and running with Derby as quickly as possible. In way of introduction
this sections provides a brief description of Derby. This is followed by
information on the skills and software required to perform the activities
presented in this document. The section ends with a brief description of what
is presented by each of the Working With Derby activities."
It says "We think you'll find Derby to be an easy to use and fully functional
RDBMS", but doesn't say how.
It says: "Through the activities in this document we hope to help you get up
and running with Derby as quickly as possible.", but doesn't say anything about
the activities, and doesn't say how.
And "we think", "we hope" don't transmit much confidence to the reader.
So, in my opinion, the following paragraph would be better:
"Welcome to Derby! This self-study guide highlights some of the more important
features of Derby, through a series of activities designed to demonstrate the
use of Derby in embedded and client-server configurations, and to help you get
up and running with Derby as quickly as possible. After performing these
activities, you will find Derby to be an easy to use and fully functional
RDBMS. This section provides a brief description of Derby, followed by
information on the skills and software required to perform the activities
presented in this document, and ends with a brief description of what is
presented by each of the Working With Derby activities."
> 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
