Committing to providing alt text for all figure images in lessons

[anisa-hawes]

I'm opening this Issue as a partial response to the recommendations outlined within Dr Kavanagh's report and discussed in Issue #2072.

I'd like to make a suggestion that we commit to providing alt text for all figure images, plots and graphs included in lessons. I'm in the process of collating some resources which I think might help us to do this well.

May I ask if anyone could confirm the liquid syntax we'll need to use? Looking at a few existing pages on our site, I think the format required will be, e.g.,:

{% include figure.html filename="file-name.png" alt="Visual description of figure image" caption="Caption text to display" %}

Is that correct?

I am not clear how alt text displays on our site at the moment. Does the alt text revert to the caption tag where there is no alt text provided?

Of course, the alt and caption text may not/often won’t match, so we need to be able confirm that users will encounter the alt where we insert it.

Let me know if you’re able to help! With thanks, Anisa

[jenniferisasi]

I had explored a lesson with alt text already in it; and VoiceOver (in a Mac) reads it OK. However, it doesn't indicate that it is reading an image.

@anisa-hawes and I are going to check an edited lesson + VoiceOver to find the perfect syntax

[anisa-hawes]

This question isn't yet solved. We've set up a test PR #2615, but find that VoiceOver does not read the new alt-text. It reads the caption, and prompts the user to activate “interaction”, only then to say “no title”.... Which is unhelpful.

[anisa-hawes]

Update: Excellent news! We have implemented some updates to _includes/figure.html which enables any alt tags included within our liquid syntax to be rendered.

Going forward, we'll need to use the following syntax:

{% include figure.html filename="file-name.png" alt="Visual description of figure image" caption="Caption text to display" %}

An important note is that Markdown styling should NOT be used within alt text, because screen readers will read any characters directly (so bold would be read as asterisks and html tags would be read as words).

Thank you for your support & input @jenniferisasi and @ZoeLeBlanc :sparkles:

My next steps will be to:

• Share this information and encourage authors and editors who are currently working on lessons to implement this best practice
• Collate some resources to help us write effective alt-text, and add some advice/guidelines to our Wiki

[rivaquiroga]

This is great! :rocket: A good resource for writing alt-text for data visualization is the article Amy Cesal wrote for the Journal of the Data Visualization Society.

[acrymble]

@anisa-hawes can we close this yet or does it still need specific action?

[anisa-hawes]

Thank you for following up @acrymble. Apologies for leaving this one hanging.

Actions:

• [x] Communicate with each of the Managing Editors about this addition
• [x] Collate resources to help us write effective alt-text
• Writing Alt Text for Data Visualization : Amy Cesal
• Web Accessibility Tutorials: Complex images : W3C
• Alt Text & Accessibility : Web Aim
• How to Write Great Image Alt Text : Catherine McNally
• The Right Way to Write Alt Text | : Natalie Gotko
• Examples of Accessible, Effective Chart Descriptions : Frank Elavsky
• Collated list of people and resources in the field Dataviz Accessibility Resources : Frank Elavsky

Note: Most of these articles warn that screen readers cut off alt text which is longer than 125 characters, but I read elsewhere that this is outdated now although being clear and succinct is recommended.

Steps to close the Issue:

• [ ] Identify some resources in languages other than English. Might others from the @programminghistorian/project-team have suggestions for useful guidance specifically in FR, ES and PT?
  • [x] Add this resource list to our Wiki somewhere (I've added it here Achieving Accessibility: Alt text, Colour, Contrast)
• [ ] Update the Figures and Images section of our Author Guidelines so that:
  • [ ] this syntax is provided: {% include figure.html filename="file-name.png" alt="Visual description of figure image" caption="Caption text to display" %}
  • [ ] this sentence is adjusted: All figures must come with a concise figure caption and endnotes where appropriate. so that it reads All figures must come with a concise figure caption, descriptive alt-text, and endnotes where appropriate.
• [x] Add this to my Editorial Guidelines milestone, because editors as well as the typesetter will need to be alert that this is needed

[rivaquiroga]

Regarding this part:

this sentence is adjusted: All figures must come with a concise figure caption and endnotes where appropriate. so that it reads All figures must come with concise alt-text, figure caption and endnotes where appropriate.

The caption is the one that should be concise, not the alt-text. The alt-text should be descriptive so that anyone using a screen reader can understand what the figure is depicting.

I'll look for some ES resources about this topic to add to our list.

[anisa-hawes]

During the past several months, I have been working with authors, translators and editors to ensure that descriptive alt-text accompanies all figure images in our lessons. This work forms part of a series of Sustainability + Accessibility checks I have developed.

A new Wiki page has been created on Descriptive Alt-text to which we can refer authors, translators and editors. This page represents part of a series of guideline documents I am developing to support the production of accessible lessons.

--

Meanwhile, I have prepared a PR #2931 to update the following pages of our website:

/en/author-guidelines
/es/guia-para-autores
/fr/consignes-auteurs
/pt/directrizes-autor