Documentation and Accessibility

Brown baby chick in front of feed sack with Cyrillic writing surrounded by brown eggs

What format needs to be accessible? PDF, HTML, or both??

Document generation engines are a big part of technical documentation these days, especially in enterprise software.

  • Most enterprise organizations no longer use Adobe tools to create PDF files or edit HTML for large software reference guides or training.
  • They create documentation through authoring tools which then export .PDF and HTML

When using an authoring tool to create documentation, both the tool and the export should be accessible. ATAG is the W3C standard for authoring tools. It has not been updated to include additions to WCAG 2.1, but those updates are easy to extrapolate. More often than not, either the tool, the export, or sometimes both, are inaccessible.

Alternate document version

In general, WCAG allows for alternate versions of non-conforming web pages. That means you can have something inaccessible under a very constrained set of conditions. In its traditional non-prescriptive manner, WCAG has two success criteria in this area, including:

G136: Providing a link at the beginning of a nonconforming Web page that points to a conforming alternate version.

G20: Ensuring that the only way to get to an inaccessible version is from a link from the accessible version

Think of it in terms of physical access:

The ADA did not make stairs illegal

The ADA requires an unspecified alternate method (it can be a ramp, elevator, transporter beam) to allow everyone to get to everything the stairs provide access to

Signage is required to tell people how to find the accessible route.

Therefore, it is categorically OK to only have a single documentation format be accessible if one of the specified WCAG success criteria is being followed.

Print only .PDF

Print only .PDF is another consideration in this analysis. Some organizations designate documentation in PDF format as “print only”. In other words, print only .PDFs are intended to be “dead tree” versions that are inherently inaccessible. When going this route, a different format would be used for the accessible version (following either the G136/G20 success criteria above). Despite being environmentally unfriendly, there are business drivers for print-only documentation, such as for reasons such as licensing or including special OCR codes or personalized links in the documentation.

Chicken and Egg — which is the source and which is the alternate?

In a perfect world, your users would tell you this through analytics.

  • Which format do your users prefer? If 90 % of your users access documentation via the web pages, the answer is fairly simple.
  • Do your users always have internet access? If the answer is no, then the .PDF should be accessible as the users will not always have access to the .HTML

If it is the other way around (the HTML is inaccessible, but the PDFs are) then putting accessible information at the top of the inaccessible HTML page about the location of the accessible .PDF is the way to provide equal access.

The Zen Approach to Accessible Documentation

“If everything is important, then nothing is important. If everything is a priority, then nothing is a priority” — Garr Reynolds, Presentation Zen

In the hypothetical perfect world, it would be optimal if all forms of documentation were accessible. But there is opportunity cost associated with this approach.

  • If you have one format accessible, and you focus energy and money on the inaccessible format, what could that energy/money be better used for? Accessible training? More manual testing resources or assistive technologies? Those may have a substantially larger impact on your users with disabilities than making a second documentation format accessible.
  • Another important consideration is both PDF and HTML are free. It would not be OK if .docx were accessible and HTML was not — it’s not equal access if you are forcing someone spend money on a MS Word license in order to view the documentation.

Unless everything your organization produces is accessible and the *last* thing left is an alternative documentation format, it is likely that the resources can be better spent elsewhere.

— — — —

with thanks to Dax CastroMark Aplet, Joseph LaFauci, Joanne Lastort, Christopher Duncan, Kate Percival, and Luella Benedetto, for contributing to the conversation on the IAAP Connected Community Platform that led me to write this article. Conclusions are my own 🙂

0 comments on “Documentation and Accessibility

Leave a Reply