Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Derby Development" <derby-dev@db.apache.org>
Received-SPF: pass (asf.osuosl.org: local policy)
Date: Tue, 26 Jul 2005 10:04:19 -0700
From: David Van Couvering <David.Vancouvering@Sun.COM>
Subject: Re: [doc] More quality improvements to the documentation
In-reply-to: <20050725200548.49311.qmail@web81609.mail.yahoo.com>
To: Derby Development <derby-dev@db.apache.org>
Message-id: <42E66D13.1030705@sun.com>
MIME-version: 1.0
Content-type: text/plain; charset=ISO-8859-1; format=flowed
Content-transfer-encoding: 7BIT
User-Agent: Mozilla Thunderbird 1.0.6 (Windows/20050716)
References: <20050725200548.49311.qmail@web81609.mail.yahoo.com>

Ooh, yes, very nice.  This is something I have struggled with in the 
past -- I click on a topic, and then to go to sub-topics I have to

I also very much like the related topics feature. 

It would be great if those of us who use the manuals could "add" related 
topics as it becomes clear they are related.  It would be even *nicer* 
if this could be done right there online without having to edit DITA files.

If you look at the PGP documentation you will see what I mean:

http://www.php.net/manual/en/install.unix.php

at the bottom of the page there is the "add a note" link.  Users can add 
notes to the page to provide more details, helpful hints, or 
complaints.  There are quite a few helpful notes added to this page.

Wouldn't it be possible to modify the DITA template to allow users to 
add notes?  We could then incorporate useful notes into the next rev of 
the docs.

David

Jeff Levitt wrote:

>I have been trying to improve the linking between
>topics in the manuals.  Specifically, I am trying to
>implement the use of "relationship tables" to improve
>the related links.  I just completed the work for the
>Getting Started Guide and thought I'd post a patch to
>show the differences and see what people think.
>
>So attached is the patch, and I am also including
>links to the generated output on my own test site:
>http://derby.mylevita.com/getstart/
>
>Summary and explanation of the changes:
>No changes will affect the PDF whatsoever.  This is
>just for the html linking.
>
>So the work involved creating a relationship table in
>the ditamap file.  This allows you to define
>relationships between topics in different sections in
>the book, not just between parents, children, and
>siblings.  I also moved introductory content for every
>topic into shortdesc tags, which has the effect of
>displaying that information in the parent topic as a
>summary of the link, or as mouse-over information in
>related links.  
>
>OK, a lot of that was mumbo-jumbo, so here's a visual
>explanation:
>
>Compare the current version of the following topic
>with my new output:
>
>http://incubator.apache.org/derby/docs/getstart/cgsinsta.html
>http://derby.mylevita.com/getstart/cgsinsta.html
>
>The original page simply lists all of the topic
>children.  The new page lists the summary information
>for each topic, which is pulled from the first
>sentence or two of each topic.  
>
>Below that, under "Related concepts" you have a link
>that I had entered in the relationship table to
>"Deployment options", which was not originally linked
>to from this section, but seemed like a good related
>link to me.  Instead of displaying the summary below
>the link, you can see the summary by moving the mouse
>over the link.  Note also that the reciprocal
>relationship occurs; "Deployment options" has a link
>to this page too.  
>
>That reciprocal relationship can be turned off when
>not needed.  So for example, since this page has a
>link in the content to "Quick start guide for
>experienced JDBC users", I didnt think it was
>necessary to list it again in the related concepts
>section.  However, I did specify that the "Quick start
>guide for experienced JDBC users" topic have a link
>back to this page in the related concepts.
>
>So please take a look at my output, and if no one has
>any objections, maybe we can get this patch committed,
>and I would be happy to take a swing at doing this for
>the rest of the docs.
>  
>