Re: [jira] Created: (DERBY-379) Doc review: Getting Started with Derby

[Myrna van Lunteren <m....@gmail.com>]

Ok, here are my comments on this doc:
  general comments using PDF: 
- version on front - should be 10.1? or leave at at 10?
- p3 - Copyright - First Edition... says 2004. Should we change this?
 Also, copyright says 1997, 2004. Should that get updated to
 2005?
- I'm not sure this can be changed, but in the PDF format, some of the 
syntax 'boxes' looked really peculiar with only one word on each line...For 
example, in this manual, the SQL Syntax bos (under 'Documentation 
conventions').
 specifics:
p 6 - section Installing Derby.
 rewrite, but (maintain the fonts, can't do it in my email program) to say 
something like:
Extract the 'bin' file. The contents will be extracted into a directory 
reflecting the file name. This directory contains the following 
subdirectories:
1. The lib subdirectory contains the Derby jar files
2. The demo subdirectory contains demo programs
3. The frameworks subdirectory contains scripts for executing utilities and 
setting up the environment
4. The javadoc subdirectory contains the api documentation that was 
generated from source code comments
5. The doc subdirectory contains the documentation
 p6 - section Using the tools and startup utilities
move sentence 'You can find similar scripts for running tools.... 
directory.' up to the previous paragraph (after '... in embedded mode'. Add 
: 'In the following sections reference is made to '/bin' which is assumed to 
mean frameworks/embedded/bin unless explicitly stated otherwise.
 p7 - section Running ij. 2nd bullet. add 4 words to end of sentence 'This 
command creates a database called...' : '...system tables and connects to 
it.'
 p8 - section Set Derby install environment variable (started p7):
change 1st paragprah to:
'During installation a base directory was created where the software was 
installed. This document assumes that directory has been named 'Derby_10'. 
This document refers to that directory as the Derby base directory.'
 p8 - section Set the class path - needs a bigger font 
 p9 - section Environment in which Derby can run
The paragraphs following contain 'Embbedded environment' and 'Client/server 
environment' twice (second time in reverse order). The text is a little 
different, but not much. I'm guessing one of this was the replacement of the 
other, but I can't figure out which. The sections seem completely equivalent 
to me - but there should be only one of each & the headings should have 
appropriate size fonts.
 p 10 - section Database connection URL
change sentence into:
'For the Derby-provided embedded driver listed in the previous section, the 
format for the database connection URL for connecting to a database is 
this:'
(the syntax listed is for the embedded driver and because the 'create=true 
is mentioned I feel we should not specify 'existing' database.)
 p12 - table with typographical conventions
The table got messed up. The first column needs to be blank for rows 2, 3 
and 4. And for row 6 too - the 'Bold, fixed-width' is superfluous in that 
field. for row 2,3 and 4, the columns need to be 'moved' to the right.
Row 5, last column, the example is invalid, replace with:
'SELECT city_name FROM Cities
 p13 - Libraries provided by Derby
add a 2 rows:
1: (bold) The locale libraries
2: derbyLocale_*.jar | needed to provide translated messages for de_DE, es, 
fr, it, ja_JP, ko_KR, pt_BR, zh_CN and zh_TW locales.
 p13 - Scripts provided by Derby
resequence the first 4 to start with frameworks/embedde/bin/dblook.
(that's the sequence the files will have alphabetically).
   
On 6/20/05, Jeff Levitt (JIRA) <de...@db.apache.org> wrote: 
> 
> Doc review: Getting Started with Derby
> ---------------------------------------
> 
> Key: DERBY-379
> URL: http://issues.apache.org/jira/browse/DERBY-379
> Project: Derby
> Type: Improvement
> Components: Documentation
> Environment: all
> Reporter: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.1.0 <http://10.1.1.0>
> 
> 
> This issue tracks comments for the Getting Started with Derby manual. The 
> deadline for posting comments isTuesday, June 28, noon Pacific time.
> 
> Some guidelines to follow when posting comments to this issue are:
> 
> - Try to make clear and concise comments about what you want changed 
> whenever possible. Provide concrete comments that say "Please change 
> <original> to <modified>" instead of generic comments like "This section 
> needs to be rewritten."
> 
> - If you're reviewing the HTML Files copy, include the URL for the page in 
> the review comment. Obtain the URL like this:
> 
> * highlight the topic in the left frame
> * right click
> * choose "Properties"
> * copy and paste the address in the pop up box.
> 
> - If you're reviewing the PDF copy, in the review comment:
> 
> * Include the page number for the PDF, and indicate whether the number is 
> the PDF sheet number or the printed page number.
> * Include the title of the section that the problem occurs in. If it's in 
> a subsection, try to include the hierarchy of titles.
> 
> - Please don't review the HTML Book copy -- it'll be time consuming to 
> match up that copy with the underlying DITA source.
> 
> 
> --
> 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
> 
>