db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Francois Orsini <francois.ors...@gmail.com>
Subject Re: [doc] More quality improvements to the documentation
Date Tue, 26 Jul 2005 17:13:44 GMT
Looks good Jeff.

The original Cloudscape documentation had a fantastic master/global
index file - it was my main front-door to me for any type of
documentation searching - I could locate anything real fast and
documents (HTML) were linked as well. I know this global index file
took a lot of time to build but it did save so much time when looking
for something in the documentation...

The MySQL online documentation also lets users add comments to the
documentation - I have to admit it has been useful when I tried to get
my way around MySQL....



On 7/26/05, David Van Couvering <David.Vancouvering@sun.com> wrote:
> 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.
> >
> >

View raw message