db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Levitt <de...@mylevita.com>
Subject [doc] More quality improvements to the documentation
Date Mon, 25 Jul 2005 20:05:48 GMT
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