db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scott hutinger <s-hutin...@wiu.edu>
Subject Re: [doc] More quality improvements to the documentation
Date Mon, 25 Jul 2005 20:19:48 GMT
I think the output of the patch is very good.  The 'mumbo-jumbo' sounds 
even better :-)

scott

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


Mime
View raw message