db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (DERBY-5184) Tables in documentation need introductions and formatting fixes
Date Fri, 08 Apr 2011 17:32:05 GMT

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

Kim Haase commented on DERBY-5184:

I recommend using the phrase "the following table" to introduce a table, rather than an <xref>
element, mainly because of the way the DITA toolkit handles table cross-references: the output
has the table title rather than the table number (possibly because in the Frames output almost
all tables are "Table 1" because table numbering starts over with a new section), so the user
would still have no indication that what followed was a table.

There are some exceptions to this rule. I don't think introductions are needed for the individual
tables in  http://db.apache.org/derby/docs/dev/ref/ref-single.html#rrefsql9241891 (in fact,
it might be good to remove the section heads here, since they duplicate the titles and force
renumbering in the frames output) and in http://db.apache.org/derby/docs/dev/ref/ref-single.html#rrefexcept71493.

I would like to suggest that every table should be a formal table with a title. The docs are
currently inconsistent in how they use choicetables and simpletables, which do not allow titles.
My reasoning is a bit indirect: only tables with titles can have a <desc> element. Ideally,
the DITA toolkit would use the <desc> element to populate the summary attribute of each
table to provide a detailed description of the table that would be used only by screen readers.
Currently we can't really use the <desc> element because it simply gets stuck after
the table caption (I plan to remove the <desc> element and use its contents as the table
introduction for the 4 topics that use one). But if we can somehow get DITA to do the right
thing with <desc>, we can eventually provide more accessibility help for tables than
introductions to the tables will provide.

WCAG (Guidelines 3 and 5) recommends avoiding layout tables. We have a few, where table format
is used solely for appearance; for example,  http://db.apache.org/derby/docs/dev/tuning/ctundepth14326.html.
For accessibility, these should not be tables.

I may also make a few formatting changes elsewhere in the topics as needed (case consistency
in titles, for instance, and paragraphing before tables for vertical spacing).

> 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:
>            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

View raw message