DITA XML and Accessibility: An Interview with Robert Johnson II

A 10 minute read written by keith May 15, 2014

GAAD DITA sketched logo

Today is Global Accessibility Awareness Day (GAAD), which is designed to promote greater awareness of accessibility issues and the ways that we can help improve how we deliver digital content for those who require it. Accessibility has long been of interest to me and I advocate it not just because it is often a requirement, but because it leads to better content for everyone.

Robert JohnsonWhen I was at the recent Content Management Strategies/DITA North America 2014 conference held in Seattle, I attended a talk by Robert Johnson II (@cliostechscribe) called "From DITA to Accessible HTML". In order to help promote awareness of accessibility issues and how it relates to DITA XML, Robert Johnson II kindly agreed to an interview at short notice in time for GAAD.

DITAWriter: Can you tell me about your role at Oracle, and why your interest in accessible content?

Robert Johnson II: When I was at Oracle (I just joined a medical device company  to guide their migration to DITA), I was a Senior Technical Writer for Endeca Information Discovery, an agile business intelligence product. In addition to my writing responsibilities, I had secondary responsibilities for accessibility, tools and technologies, and coordinating our DITA practices.

I started shortly after Endeca was acquired by Oracle. One of Oracle's requirements after the acquisition was that we implement accessibility for our products and our documentation. I had become familiar with accessibility earlier in my career, so I agreed to accept the responsibility for implementing accessibility in our documentation.

I also have a personal interest in accessibility. My mother is blind due to diabetes. My uncle experiences tinnitus (ringing in the ears) severe enough that he was ineligible for service during the Vietnam era. Both my son and my daughter have ADD, and my son has also been diagnosed with Asperger’s Syndrome. One of my daughter's closest friends in school has cerebral palsy. And my wife is a special education teacher.

DITAWriter.com: So why is accessible content important?

Robert Johnson II: When I described the people in my life with disabilities earlier, the point was not to overshare. Almost everyone reading this knows someone with a disability, whether visual (such as blindness or colorblindness), auditory (deafness or milder hearing loss), motor ability (multiple sclerosis, cerebral palsy, ALS), or neurological. In fact, most of us know several people with disabilities.

The market for accessible content and products is huge. The World Health Organization reports that 15% of the world's population lives with a disability. That's about one in every 6 people. In the 2010 US census, more than 56 million people reported a disability, which is close to 19% of the population. It's not easy to discount this population as irrelevant to B2B products either, as in the same census 41% of the working age population (21-64) with a disability are employed.

Moreover, anyone can be temporarily or situationally disabled. Someone that has broken their arm is temporarily disabled. Or think of trying to check your voice mail in a loud, crowded bar. In that situation, your voice mail is functionally inaccessible. As we grow older, the likelihood that we will experience some form of functional disability increases significantly.

If your company does business with the government, you have another good reason to make your content accessible: government procurement laws prefer accessible products. At the U.S. Federal level, this is covered under Section 508. If you are trying to sell a product that is not accessible, and your competitor's product is accessible, the government must purchase the competitor's product, even if your product meets or exceeds all other requirements. Similar regulations also exist at the state and local levels. Some overseas governments are even stricter; in those places, accessibility is not a preference, it is a requirement.

In the end though, offering accessible content is simply the right thing to do.

DITAWriter: What are the resources those working with DITA ought to know about regarding accessibility?

Robert Johnson II: The key resource for DITA authors to be aware of is the Web Content Accessibility Guidelines (WCAG), currently at version 2.0.

If you are developing custom delivery (especially custom HTML delivery), you should also be aware of the Accessible Rich Internet Application (ARIA) standards. According to the W3C, the ARIA standard:

[D]efines a way to make Web content and Web applications more accessible to people with disabilities. It especially helps with dynamic content and advanced user interface controls developed with Ajax, HTML, JavaScript, and related technologies.

DITAWriter: One of WCAG's guidelines says that content should be "perceivable". How does this apply to DITA HTML output?

Robert Johnson II: The first thing that comes to mind when you think about ensuring that content is perceivable is that you need to provide text alternatives to non-text content, such as images. HTML provides an alt attribute on the element. For example:

A typical whifflejangle

Assistive technology uses the alt attribute to communicate about the image to the user. A screenreader, for example, reads aloud the value of the alt attribute.

DITA originally provided an exact parallel to the alt attribute in the element:

A typical whifflejangle</code></pre>

DITA 1.2 introduced an child element for the element.

A typical whifflejangle" 

This option is preferred over the original implementation as individual tags are easier to access than attributes are for machine translation. The original implementation is deprecated.

It is important to ensure that the value of the </code>is meaningful. A single word usually isn't enough. Just using "Whifflejangle" doesn't convey a lot of information. Adding one or two works may be enough to convey additional meaning; for example "Whifflejangle dialog" or "A typical Whifflejangle". Longer text may be appropriate (for example "Whifflejangle dialog showing configuration to produce a port lee scupper"), but don't go overboard. If you need more than a sentence or two, put the description in the running text. It usually considered acceptable in that case to reference the running text in the </code>.</p>

Other non-text content that needs text alternatives are embedded objects such as video, audio, or PDFs. In HTML, the body of the object should contain text content, which will be used by the assistive technology.

All about whifflejangles

In DITA, use the </code>child of the </code>element to provide this content:</p>
All about whifflejangles 

When you publish HTML output, the value of the </code>child is output in the body of the </code>, embedded in a </code>element, which allows access for CSS to apply styling.</p>

As with images, ensure that the text is meaningful. And keep in mind that objects themselves have accessibility guidelines. Videos in particular must be accessible under the 21st Century Communications and Video Accessibility Act (CVAA).

DITAWriter: At your CMS NA/DITA presentation you said that we are already using "ASCII art" in our DITA-based documentation. What did you mean by that?

Robert Johnson II:  Most of us have seen a picture composed using ASCII characters. A simple example would be a heart made using a left angle bracket and the number 3 character:  <3. Some can get pretty elaborate, and while they are visually impressive, they are meaningless to a user that can't see.

You might say, "But we don't use any ASCII art."  Suppose, however, you format a menu cascade like this:

Choose File > New.

When you use the right angle bracket as an arrow in a menu cascade in this manner, the angle bracket is considered ASCII art.

The WCAG 2.0 brings us some good news, in that you can use the abbreviation tag in HTML (</code>) to provide an alternative rendering for the angle bracket:</p>

Choose File > New.

Assistive technology, like a screenreader, should detect the content of the </code>element and render the value in the title attribute. So the screenreader would say: "Choose File and then New."</p>

Unfortunately, DITA doesn't currently provide a way to implement this. I've been told that the issue has been logged and a future version of the DITA-OT will provide an appropriate rendering in the future if it detects an angle bracket in a menu cascade.

DITAWriter: What are the issues facing DITA table output and accessibility?

Robert Johnson II: When considering accessibility, you have to begin with your table design. Remember that some disabled users will be building a mental model of the table in their head without the benefit of seeing it. So keep designs simple. Try and keep to very basic designs, with column headers in the first row and row headers in the first column. Also, avoid merging cells. Merged cells can cause problems navigating a table using assistive technology. Moreover, they also make it more difficult for the disabled user to build a mental model of the table.

When you implement the table, it is best to use the

(CALS table or OASIS Table Exchange Model). The element includes all that you need to make a fully accessible table. Of the other options available, does not include features to provide accessible output, and does not provide for a caption.

To support accessibility, a table must have either a </code>child or a value in the summary attribute. It's also valid to use both, but if you use both, each must have a different value. If both the summary attribute and the </code>have the same value, the screenreader repeats the text. This results in a stutter, which can confuse users of assistive technology.</p>

Outputting the </code>is straightforward. Simply use the </code>child of the <code><table></code>element. When you publish to HTML, the value of the <code><title></code>child is output into the <code><caption></code>.</p> <p>Outputting the summary attribute is not as easy, as it is not directly supported. Fortunately, a hook was introduced in <a href="http://dita-ot.github.io/">DITA Open Toolkit</a> 1.6 that you can use to output the summary attribute. In the XSL stylesheet dita2htmlImpl.xsl, use the following template: </p> <pre> <code><xsl:template match="*[contains(@class,' topic/table ')]" mode="generate-table-summary-attribute">.</code></pre> <p>So, for example, you could use the <code><desc></code>child of the <code><table></code>element, and add XSLT code to this template to output the text node of the <code><desc></code>child of the <code><table></code>in your DITA source so that the summary attribute of the <code><table></code>element appears in the published HTML.</p> <p>Table header and data cells must also be associated to facilitate navigation using assistive technology. Right now, only one option is supported in DITA: using IDs and column and row headers to associate cells with their headers.</p> <p>In <code><table></code>element, specify rowheader="firstcol". This specifies that the value in the first column is used as a header for the row.</p> <p>Optionally, use <code><colspec></code>elements to define the columns. In each <code><colspec></code>element, specify a value for the colname attribute. Note that if you do not use this option, a default column header ID is generated to facilitate navigation.</p> <p>Another option is available in HTML, using the scope attribute to associate header and data cells, but this option is not supported in DITA 1.2 and earlier. Look for support for this option in DITA 1.3 though.</p> <p><strong>DITAWriter:</strong> From your talk you mentioned that Section 508 means that having accessible content is mandatory when selling to the U.S. Federal government. What are the consequences for documentation that is not accessible?</p> <p><strong>Robert Johnson II:</strong> Just to clarify, Section 508 mandates a clear preference for procuring accessible products. So if two products are competing, and one is accessible and the other is not, the government is obliged to acquire the accessible product. In fact, the government must acquire the accessible product even if the other product exceeds the accessible product in all other ways.<br /> <br /> So if documentation has gaps in accessibility, it could hinder your ability to sell to government customers. The reality is that it's rare for a product to be completely free of accessibility issues. Your company's product managers and accessibility experts will determine which accessibility issues need to be addressed and those you can live with.</p> <p><strong>DITAWriter:</strong> Where do you see DITA and accessibility going in the near future? Can we expect anything in the coming DITA Open Toolkit 2.0/DITA 1.3 specification?</p> <p><strong>Robert Johnson II:</strong> DITA 1.3 is scheduled to include enhancements that expand the options for implementing accessibility in tables to match the options available in HTML. While it's good to enhance the flexibility of DITA, authors also need to remember to keep table design simple.</p> <p>As for the DITA-OT, the output of relationship tables needs attention. When generated to HTML, relationship tables result in a set of links. Currently, these links are formatted as a set of <code><div></code>tags, which was valid under WCAG 1.0. But WCAG 2.0 recommends formatting sets or lists of links using link markup. I don't anticipate that happening in the DITA-OT 2.0 release, but it could happen in the following release.</p> <p>I'd like to see DITA provide functionality to support formatting right angle brackets (>) using the HTML abbreviation tag, as I discussed earlier. An interim solution would be for the DITA-OT to detect use of the angle bracket in menu cascades and add the abbreviation tag with a default value. Again, I don't foresee that happening in the DITA-OT 2.0 release, but could be implemented in the following release. Ideally, it would be good to for DITA to provide functionality that allowed the author to define the value of the title attribute of the abbreviation tag in the DITA source. That will require an enhancement to the DITA specification as well as the DITA-OT. Given the current state of development of DITA 1.3, I don't foresee that happening, though it could come in a future version of DITA.</p> </div></code></p></colspec></code></colspec></code></p></table></code></p></table></code></table></code></desc></code></table></code></desc></code></p></xsl:template></code></pre></caption></code>