Edit online

Writing Guidelines for Accessible Documentation

To create accessible content, good authoring practices involve following guidelines, such as marking table headers, using semantic elements where available, and using alternative text for images.

Edit online

Accessible Images

Images must have text alternatives that describe the information or function represented by them.

Short Text Equivalents for Images

When using the <image> element, specify a short alternative text with the <alt> element.

<image href="puffin.jpg">
  <alt>Puffin figure</alt>
</image>

Long Descriptions of Images

For complex images, when a short text equivalent does not suffice to adequately convey the function or role of an image, provide additional information in a file designated by the <longdescref> element.

<image href="puffin.jpg">
  <alt>Puffin figure</alt>
  <longdescref href="http://www.example.org/birds/puffin.html"
               scope="external"
               format="html"/>
</image>
Edit online

Accessible Image Maps

For image maps, text alternatives are needed on both the <image> element itself (to describe the informative context) and on each of the <area> elements (to convey the link destination or the action that will be initiated if the link is followed). The <xref> content within the <area> element contains the intended alternative text or hover text for that image map area.

<imagemap id="gear_pump_map">
  <image href="../images/Gear_pump_exploded.png" id="gear_pump_exploded">
    <alt>Gear Pump</alt>
  </image>
  <area>
    <shape>circle</shape>
      <coords>172, 265, 14</coords>
      <xref href="parts/bushings.dita#bushings_topic/bushings" 
            format="dita">Bushings</xref>
  </area>
  <area>
      <shape>circle</shape>
      <coords>324, 210, 14</coords>
      <xref href="parts/ports.dita#ports_topic/sucction_port" format="dita"
        >Suction Port</xref>
   </area>
</imagemap>
Edit online

Accessible Tables

Accessible HTML tables need markup that indicates header cells and data cells and defines their relationship. Header cells must be marked with <th>, and data cells with <td>, to make tables accessible. For more complex tables, explicit associations may be needed using @scope, @id, and @headers attributes.

When you implement the table, it is best to use the <table> element (CALS table or OASIS Table Exchange Model). The <table> element includes all that you need to make a fully accessible table.

Edit online

Table with Header Cells in the Top Row Only

For this type of table, you have to embed the table rows in the <thead> element.

Table 1. Example: Oxygen Events
Event Date Location
Evolution of TC 2018 May 31 - June 1, 2018 Sofia, Bulgaria
Markup UK June 9 - 10, 2018 London, United Kingdom
Balisage 2018 - The Markup Conference July 31 - August 3, 2018 Rockville, Maryland, USA 
<table colsep="1" rowsep="1" frame="all">
  <title>
    <b>Oxygen Events</b>
  </title>
  <tgroup cols="3">
    <colspec colname="COLSPEC0" colwidth="1*"/>
    <colspec colname="COLSPEC1" colwidth="1.1*"/>
    <colspec colname="newCol3" colwidth="1*"/>
    <thead>
      <row>
        <entry colname="COLSPEC0" valign="top">Event</entry>
        <entry colname="COLSPEC1" valign="top">Date</entry>
        <entry>Location</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>Evolution of TC 2018</entry>
        <entry>May 31 - June 1, 2018</entry>
        <entry>Sofia, Bulgaria</entry>
      </row>
      <row>
        <entry>Markup UK</entry>
        <entry>June 9 - 10, 2018</entry>
        <entry>London, United Kingdom</entry>
      </row>
      <row>
        <entry>Balisage 2018 - The Markup Conference</entry>
        <entry>July 31 - August 3, 2018</entry>
        <entry>Rockville, Maryland, USA</entry>
      </row>
    </tbody>
  </tgroup>
</table>
Edit online

Table with Header Cells in the First Column Only

For this type of table, you have to set the rowheader="firstcol" attribute on the <table> element to identify the header column.

Table 2. Example: Oxygen Events
Event Evolution of TC 2018 Markup UK Balisage 2018 - The Markup Conference
Date May 31 - June 1, 2018 June 9 - 10, 2018 July 31 - August 3, 2018
Location Sofia, Bulgaria London, United Kingdom Rockville, Maryland, USA 
<table rowheader="firstcol" colsep="1" rowsep="1" frame="all">
  <title>
    <b>Oxygen Events</b>
  </title>
  <tgroup cols="4">
    <colspec colname="COLSPEC0" colwidth="1*"/>
    <colspec colname="COLSPEC1" colwidth="1.1*"/>
    <colspec colname="newCol3" colwidth="1*"/>
    <colspec colname="newCol4" colwidth="1*"/>
    <tbody>
      <row>
        <entry>Event</entry>
        <entry>Evolution of TC 2018</entry>
        <entry>Markup UK</entry>
        <entry>Balisage 2018 - The Markup Conference</entry>
      </row>
      <row>
        <entry>Date</entry>
        <entry>May 31 - June 1, 2018</entry>
        <entry>June 9 - 10, 2018</entry>
        <entry>July 31 - August 3, 2018</entry>
      </row>
      <row>
        <entry>Location</entry>
        <entry>Sofia, Bulgaria</entry>
        <entry>London, United Kingdom</entry>
        <entry>Rockville, Maryland, USA</entry>
      </row>
    </tbody>
  </tgroup>
</table>
Edit online

Table with Header Cells in the Top Row and First Column

For this type of table, you can use <thead> to identify header rows and @rowheader to identify a header column.

Table 3. Example: Bus Timetable
Monday Tuesday Wednesday Thursday Friday
09:00 - 11:00 Closed Open Open Closed Closed
11:00 - 13:00 Open Open Closed Closed Closed
13:00 - 15:00 Open Open Open Closed Closed
15:00 - 17:00 Closed Closed Closed Open Open 
<table id="table_dqk_n24_vdb" rowheader="firstcol" colsep="1" rowsep="1" frame="all">
   <title>Example: Bus Timetable</title>
   <tgroup cols="6">
     <colspec colnum="1" colname="col1"/>
     <colspec colnum="2" colname="col2"/>
     <colspec colnum="3" colname="col3"/>
     <colspec colnum="4" colname="col4"/>
     <colspec colnum="5" colname="col5"/>
     <colspec colnum="6" colname="col6"/>
     <thead>
       <row>
        <entry/>
        <entry>Monday</entry>
        <entry>Tuesday</entry>
        <entry>Wednesday</entry>
        <entry>Thursday</entry>
        <entry>Friday</entry>
       </row>
     </thead>
     <tbody>
      <row>
        <entry>09:00 - 11:00</entry>
        <entry>Closed</entry>
        <entry>Open</entry>
        <entry>Open</entry>
        <entry>Closed</entry>
        <entry>Closed</entry>
      </row>
      <row>
        <entry>11:00 - 13:00</entry>
        <entry>Open</entry>
        <entry>Open</entry>
        <entry>Closed</entry>
        <entry>Closed</entry>
        <entry>Closed</entry>
      </row>
      <row>
        <entry>13:00 - 15:00</entry>
        <entry>Open</entry>
        <entry>Open</entry>
        <entry>Open</entry>
        <entry>Closed</entry>
        <entry>Closed</entry>
      </row>
      <row>
        <entry>15:00 - 17:00</entry>
        <entry>Closed</entry>
        <entry>Closed</entry>
        <entry>Closed</entry>
        <entry>Open</entry>
        <entry>Open</entry>
      </row>
    </tbody>
  </tgroup>
</table>