[ 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:
http://derby.mylevita.com/getstart/getstartderby.pdf
http://derby.mylevita.com/getstart/
http://derby.mylevita.com/adminguide/derbyadmin.pdf
http://derby.mylevita.com/adminguide/
http://derby.mylevita.com/devguide/derbydev.pdf
http://derby.mylevita.com/devguide/
http://derby.mylevita.com/ref/refderby.pdf
http://derby.mylevita.com/ref/
http://derby.mylevita.com/tools/derbytools.pdf
http://derby.mylevita.com/tools/
http://derby.mylevita.com/tuning/tuningderby.pdf
http://derby.mylevita.com/tuning/
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:
http://incubator.apache.org/derby/docs/ref/crefmpref1002477.html
Now let's look at it in my new output:
http://derby.mylevita.com/ref/crefmpref1002477.html
As for the related links, let's look at a topic that is a child with several
siblings.
Here is the CURRENT version:
http://incubator.apache.org/derby/docs/devguide/cdevdvlp96597.html
And here is my new patched version, which has dynamically created links to its
siblings divided out by reference and task information:
http://derby.mylevita.com/devguide/cdevdvlp96597.html
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:
http://incubator.apache.org/derby/docs/tools/ctoolsijtools26429.html
Here is the same doc in my output, pulling in the first few sentences of
several of the linked sibling topics as a summary:
http://derby.mylevita.com/tools/ctoolsijtools26429.html
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:
http://derby.mylevita.com/ref/refderby.pdf
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: 10.1.1.0
> Attachments: fixpatch.diff
>
> I will soon be attaching a patch that will desacribe the changes I want to
> make in more detail...
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
