db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Rick Hillegas (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (DERBY-5184) Tables in documentation need introductions and formatting fixes
Date Thu, 14 Apr 2011 15:51:05 GMT

    [ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13019872#comment-13019872
] 

Rick Hillegas commented on DERBY-5184:
--------------------------------------

Hi Kim,

Thanks for working on this issue. Here are answers to the questions you posed:

>ttoolsimporting.dita, Importing data using the built-in procedures (http://db.apache.org/derby/docs/dev/tools/ttoolsimporting.html
-- don't worry, the formatting was fixed a while ago, it just hasn't shown up >on the site):
>
>In the third row of the table, there are references to the insertColumns and columnIndex
parameters. Should this not be INSERTCOLUMNS and COLUMNINDEXES (plural)?

Yes, that looks better to me.

>cadminappsclient.dita, Accessing the Network Server by using the network client driver
(http://db.apache.org/derby/docs/dev/adminguide/cadminappsclient.html):
>
>The second table lists a retrieveMessageText URL attribute corresponding to the retrieveMessageText
property. The Reference Manual documents no such attribute. Is there an equivalent or should
this >cell say "None"?

Turns out there is such an URL attribute. Looks like we need to add it to the Reference Guide.

Thanks,
-Rick


> Tables in documentation need introductions and formatting fixes
> ---------------------------------------------------------------
>
>                 Key: DERBY-5184
>                 URL: https://issues.apache.org/jira/browse/DERBY-5184
>             Project: Derby
>          Issue Type: Sub-task
>          Components: Documentation
>    Affects Versions: 10.7.1.1
>            Reporter: Kim Haase
>            Assignee: Kim Haase
>            Priority: Minor
>
> Many tables in the Derby documentation appear abruptly, with conceptual prose followed
immediately by a table (with or without a title). Here are some examples:
> http://db.apache.org/derby/docs/dev/devguide/devguide-single.html#tdevupgradedb
> http://db.apache.org/derby/docs/dev/adminguide/adminguide-single.html#cadminappsclient
> http://db.apache.org/derby/docs/dev/ref/ref-single.html#rrefjdbc27734
> There is no specific accessibility requirement that tables be properly introduced, but
many companies' technical writing style guides require or strongly recommend it. Moreover,
the WCAG guidelines have the following statements (http://www.w3.org/TR/WCAG10/#context-and-orientation):
> "Content developers should make content understandable and navigable. This includes not
only making the language clear and simple, but also providing understandable mechanisms for
navigating within and between pages. Providing navigation tools and orientation information
in pages will maximize accessibility and usability. ... The theme of making content understandable
and navigable is addressed primarily in guidelines 12 to 14."
> Therefore, in the interest of accessibility, each table should be introduced with some
indication that a table is coming. 
> Further details will be provided in comments.

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira

Mime
View raw message