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