[jira] Updated: (DERBY-2390) DOCS - Merge Working with Derby and Getting Started Guide

["Laura Stewart (JIRA)" <ji...@apache.org>]

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