[jira] [Commented] (DERBY-5184) Tables in documentation need introductions and formatting fixes

["Kim Haase (JIRA)" <ji...@apache.org>]

    [ 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