Derby Documentation Feedback

[si...@insession.com]

Hi,

I'm new to Derby and firstly I have to say the content of the 
documentation is excellent.

The main improvements I feel that could be made are in how it is 
packaged/structured and increasing the amount of hyperlinking to 
information. 

I have found navigating through the documentation a bit slow and 
cumbersome, especially when you don't have a left hand frame that has the 
table of contents you can use to navigate with.  For example follow this 
documentation trail:

* http://incubator.apache.org/derby/manuals/develop/develop02.html
* Click on the "JDBC Applications and Derby Basics" link in the Contents
* You are presented with two sentences before you have to click the next 
page link.  Click the next page link.
* You get one page of Application Development overview.  Click the next 
page link.
* You get one sentence in the Derby Embedded Basics page.  Click the next 
page link.

I just felt that I was moving between pages (by clicking on "Next Page") 
more than I had to.

A few times I have jumped directly to a subtopic from the Contents page, 
but found I have missed reading something important in an earlier subtopic 
earlier in the chapter that was on a separate page.  It seems as though it 
would be more user friendly if we could have a table of contents in a left 
hand frame and have all the topics for a chapter in the one html document 
(displayed in the right frame).

I have also found that I had to read a number of the manuals to be able to 
get Derby running with the IBM DB2 Universal Driver.  It would be nice if 
the three manuals could be generated into a single PDF file that have 
hyperlinks across the manuals, so for example when I am say reading the 
Reference manual and it refers to something in the Tuning manual, I can 
just click on a link to go to the appropriate section in the tuning 
manual.  Also one would then be able to do a search of the PDF through all 
the manuals and print the documentation.

Not sure how feasible all this is,  maybe someone who has experience with 
Apache Forrest and Apache FOP could comment.

Any other new Derby users have any comments on the documentation?

Regards,

John Sisson

Re: Derby Documentation Feedback

["Jean T. Anderson" <jt...@bristowhill.com>]

sissonj@insession.com wrote:
...

>The main improvements I feel that could be made are in how it is 
>packaged/structured and increasing the amount of hyperlinking to 
>information. 
>  
>
...

There was a lengthy thread on derby docs at

http://nagoya.apache.org/eyebrowse/BrowseList?listName=derby-dev@db.apache.org&by=subject&from=651389&to=651389&first=1&count=15

It's a recurring theme, so this might be a fine time to track the issue in JIRA. That much said, I can't get to JIRA this morning. I'll try to remember to log it -- or feel free to beat me to it.

 -jean