Software documentation is part of accessibility

About the two aspects of accessible documentation and how it affects your bottom line

Posted by Anna Monus on September 06, 2017

We mostly discuss accessibility as a way to enable people with disabilities to use a tool (website, application, etc.) with as little information loss as possible. However, the accessibility needs of users who don't have any disabilities but experience other kinds of hardships are less widely discussed.

The lack of knowledge on a given subject is such a hardship. Therefore, providing quality technical documentation to users is an essential part of accessibility. In case of open-source tools, this is probably even more important. Here, users don't simply want to use the tool but many of them would also contribute to the code.

If you have ever had to use poorly documented software you know what I am talking about. Boring, badly structured, and user-hostile documentation can make people give up on a tool, just like an overly complicated purchasing process can result in shopping cart abandonment on eCommerce websites.

Two types of technical documentation

Essentially, there are two types of technical documentation (however, you might find more, for instance this article mentions eight types):

  1. documentation created for end-users
  2. documentation created for developers

End-user documentation

Companies tend to focus more on end-user documentation; you can find nice and user-friendly examples of this kind of docs. However, even the best designed end-user docs tend to lack crucial accessibility features (e.g. sufficient color contrast, or captioning for instructional videos).

For instance, have a look at Salesforce's Learning Centre. Overall, they did a great job with the docs. The information is well-structured and logical, and the docs don't use too much technical jargon.

On the other hand, you will find that some of the necessary accessibility features are lacking. For example, links are distinguished only by color instead of providing a non-color designator such as an underline.

Salesforce Learning Centre - Documentation Accessibility

Developer documentation

Technical documentations created for developers had been in a poor state for many years. They didn't simply lack accessibility features but also used unstructured text blocks, unreadable fonts, and small line height, lacked table of contents, and were visually unappealing on the whole.

The rise of video tutorials made the scene of developer docs much better. At about the same time, well-designed documentations began to appear.

The first developer documentation I really liked was the Zurb Foundation Docs. It has improved a lot since I first saw it, but even the earlier versions were designed, written, and structured in a way that made me want to learn.

Foundation Docs - Documentation Accessibility

Atlassian's Git Tutorials constitute another good example for user-friendly developer documentation. They are just as well-structured as the Foundation Docs but also come with great explanatory illustrations (in SVG!) and a downloadable cheatsheet.

Atlassian Git Docs - Documentation Accessibility

While both Foundation Docs and Git Tutorials present the information in a way that is accessible to users without any knowledge on the subject, you will find some accessibility problems in both, that may hinder users with disabilities (for instance, color contrast problems).

Two levels of documentation accessibility

Basically, documentation accessibility has two levels:

  1. The docs need to be accessible for users without sufficient knowledge of the tool.
  2. The docs need to be accessible for users who may have different disabilities.

The two levels can also intersect, as there can be users who are affected by both problems (i.e. don't have the sufficient knowledge plus have a disability).

The three examples I mentioned in this article (Salesforce, Foundation, Atlassian) handle the first level of documentation accessibility really well, as they:

  • don't use technical jargon, or if they do they give the necessary explanation
  • provide menus / widgets / table of contents to ease navigation
  • structure pages (careful typography, enough white space, vertical rhythm, etc.)
  • provide illustrations or instructional videos
  • provide examples of usage, demos, or code snippets

They also partially implement the second level of accessibility, however you'll find issues here and there with things such as color contrast, link visibility, video captioning, etc.

Can documentation be perfectly accessible?

I don't know if perfectly accessible docs exist or not. If they do they should implement both levels of documentation accessibility. It's certainly not something easy to accomplish, as there are so many things to pay attention to.

However, documentation accessibility is still an important part of accessibility. First, because we shouldn't exclude users with disabilities from adopting new technologies, but also because it greatly impacts how many people are willing to go the extra mile to pick up a new tool.