[
https://issues.apache.org/jira/browse/DERBY-2390?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Laura Stewart updated DERBY-2390:
---------------------------------
Attachment: getstartderby.pdf
Attached is an updated PDF of the Getting Started guide, which now includes the
Acivities in the Working With Derby guide. The Acivities from WWD now form a
"tutorial" for new users.
Kim - if you want to see the dita source, I can zip it up and attach it as well.
Because of this merger, many of the topics had to be updated in the sections
prior to the Tutorial.
What follows are some issues/questions and notes for you to keep in mind as you
review the PDF.
Issues/Questions:
1. Pay particular attention to the environment variables discussion. If the
user sets all of the variables, then what is needed in the Activities? Should
the CLASSPATH environment variable be added to this section?
2. The section on working with the tool scripts was originally designed to use
the scripts to setup up the classpath (not really about running the tools).
Because these topics weren't clear (to me) I restructured them. Now that we
have the derbyrun.jar file, is this section still necessary for setting up the
classpath? Should a new topic describing the derbyrun.jar file be added? The
current section appears just after the environment variable section, and
includes the manual way to set the CLASSPATH.
3. Do we explain the CLASSPATH well enough? What is missing?
4. Activities - Please check the steps very carefully. Because the environment
variables (at least DERBY_HOME) should already be set up, I removed any
reference to doing that task. I also removed the instructions to "change
directory (cd) to the directory ..." that were in many of the activities
because this should be a known command to the users... and it is shown
explicitly in the first activity.
5. Examples (system responses) - I updated the system responses in the
Activities to reflect May instead of January. Should they also be updated to
reflect 10.3 instead of 10.2.2? Do we need to specify a valid svn revision to
use if we update the version, or is that overkill?
6. I don't think that we do a good job of describing what the Network Server
is. The term just shows up. Where should this be explained and how should it
be described?
7. Consistency re: embedded and client/server. In some places we say "embedded
configuration" or "embedded mode" yet in both the "Quick start guide for
experienced JDBC users" and the "Terminology" sections at the end of the
Getting Started Guide, we use "embedded environment". There is the same problem
with client/server.
Notes:
Other things that I changed:
• In tables that show both UNIX and Windows commands, I moved UNIX before
Windows. Several reasons for this. 1) I have the impression that most people
are running Derby on UNIX. 2) UNIX comes before Windows alphabetically.
• I broke up topics for several reasons. Mostly to help me, representing the
novice user, to better understand the info. If I oversimplified the info,
please let me know. Here are some of my reasons:
o Simplify the content.
o Organize the information more logically
o Put task info into task topics (instead of concepts)
• Many, but not all, choice tables were converted to simple tables. I did this
for formatting reasons and as soon as I figure out how to change the formatting
in the xsl files, I will change them back. But for the foreseeable future, the
formatting is better with simple tables (which was a recommendation by Kim).
I'd appreciate any comments that you have about this merger.
> 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
> Assigned To: 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.
