db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jeff Levitt (JIRA)" <derby-...@db.apache.org>
Subject [jira] Updated: (DERBY-394) Fix for doc formatting, presentation, overall quality
Date Mon, 27 Jun 2005 18:56:04 GMT
     [ http://issues.apache.org/jira/browse/DERBY-394?page=all ]

Jeff Levitt updated DERBY-394:

    Attachment: fixpatch.diff

The attached patch fixes a number of problems and improves the overall quality of the documentation,
and tries to make use of several DITA toolkit features that we haven't been using up until
now.  In particular, I started with an edit to improve the quality of the content in the Server
and Admin guide, correcting grammar, punctuation, tagging, etc.  However, a detailed edit
such as this takes more time than I have before we release, so I think this is something I'd
like to do in the future to other books, one by one.  However, I did do a large amount of
work to all six manuals to improve their tables and related links.  

My changes do not affect much of the content itself, but rather the formatting and presentation.
 Although some changes were made to the actual content to improve grammar, this shouldn't
affect any comments made for the currently running doc reviews, as the changes were so minor.

Since this patch is so large (directly affects around 440 DITA files while affecting output
for much more), I decided to place sample output on my own website.

To access the docs, use the following direct links for PDF's and HTML, respectively:







What follows is a more detailed set of examples of the major changes I made to all 6 books.

1.  Added more related links.  DITA can dynamically create related links separated by conceptual
info, task info, and reference material to the bottom of each page of each book.  This means
that not only does it place a link to the parent topic of each file, but it also adds sibling
links and children links.  When I originally created the DITA files for these books, I didn't
account for this.  Thus, some of the related links appear duplicated (one link would be my
hard-coded link, and one would be the DITA generated link.  For example, take a look at this
page in the CURRENT set:
Now let's look at it in my new output:

As for the related links, let's look at a topic that is a child with several siblings.
Here is the CURRENT version:
And here is my new patched version, which has dynamically created links to its siblings divided
out by reference and task information:

2.  Implemented use of the <shortdesc> tag.  If we separate the first few sentences
of each topic from the rest of the content by placing them in a <shortdesc>, the result
is that if the parent topic or any siblings have a link to that topic generated by DITA, then
the content in the shortdesc tag is also pulled and used as a summary of the topic.  For example,
here is a CURRENT doc:
Here is the same doc in my output, pulling in the first few sentences of several of the linked
sibling topics as a summary:
It should be noted that I didn't have time to put info for EVERY topic in the shortdesc tag.
 We can do this as time goes by.

3.  Improved badly-formed tables.  Let's take a look at the PDF's for this one.  On page 140
(sheet 142) of the CURRENT Ref manual at http://incubator.apache.org/derby/docs/ref/refderby.pdf,
you'll notice the table looks horrible, and the row heading does not match the content.  In
my patched version, the information has been reorganized into many smaller tables that are
correctly formatted.  See page 139 (sheet 141) of:

Finally, for the Server and Admin guide, I made such editorial changes as fixing grammar,
spelling, and punctuation, removal of italics and bold type where it wasn't needed, and removal
of empty topics.  I also made small changes like replacing references to "chapter" with "section"
since if you are looking at the html, the word "chapter" could be misleading.  There were
many more such minor changes, and I would suggest comparing the current output with my own
new output, or take a look at the patch, if you want to see the differences.

I think this patch should be committed before any patches are made to the docs based on the
doc reviews, since those changes will cause conflicts to this one if this one isn't already
in the baseline.

> Fix for doc formatting, presentation, overall quality
> -----------------------------------------------------
>          Key: DERBY-394
>          URL: http://issues.apache.org/jira/browse/DERBY-394
>      Project: Derby
>         Type: Improvement
>   Components: Documentation
>  Environment: all
>     Reporter: Jeff Levitt
>     Assignee: Jeff Levitt
>      Fix For:
>  Attachments: fixpatch.diff
> I will soon be attaching a patch that will desacribe the changes I want to make in more

This message is automatically generated by JIRA.
If you think it was sent incorrectly contact one of the administrators:
For more information on JIRA, see:

View raw message