Issue stemming from the CF Workshop 25 Hackathon session '(Digital) accessibility of the CF Convention document'. As chair of the session, I want to capture our agreed goals in formal Issues to track progress. @ChrisBarker-NOAA was also in the Hackathon and made good progress towards this one - thanks Chris (please do add to, clarify or query anything I say here to summarise if you wish)!
Title
Accessibility (& SEO): add informative 'alt' text to all figures
Moderator
n/a or TBC - likely not needed as this is an infrastructure change, and not controversial?
Moderator Status Review [last updated: YYYY-MM-DD]
n/a or TBC
Requirement Summary
Ensure all figures currently in the canonical CF Conventions document have considered, informative 'alt' (alternative) descriptions included for the HTML build (may also be possible to view in a PDF build depending on viewer). This means adding carefully-considered text to an 'alt' property for every image defined in the document.
Technical Proposal Summary
Digital accessibility good practice includes adding 'proper' descriptions of images, including figures and schematics, in the designated 'alt' element.
Alt text is a standard way to aid visually-impaired users to understand what an image is showing, which can be read by screen readers for example, and it is also beneficial because:
- search engines (and therefore, AI chatbots which are becoming evermore popular) use it to interpret the intention and themes etc. of images, which can make the images more likely to come up in searches or chatbot queries;
- should there be bad connection or if GitHub Pages is playing up or similar meaning images can't load, alt text is displayed as a back-up, and it is more useful to have a description of what an image would show that nothing at all, in those cases.
At present, as we discovered in the Hackathon, the AsciiDoc build of the canonical document injects text into 'alt' such that it is defined (and therefore we 'pass' tools that check that such an attribute exists) - but that text is simply the name of the image minus its extension, as defined in the 'images' directory. So, the 'alt' attribute is present on all Figures but not with values corresponding to intended use. For example, from use of browser developer tools ('inspect') we see that the image for Figure 4.1 has in its HTML img image embed element the property alt="leap second timelines" which is the name of the image from the directory (images/leap-second-timelines.svg), and so on.
Towards resolving this issue, we need to replace this default alt text introduced by AsciiDoc with, for each Figure, an appropriate text description. Good practice for alt text is covered in such developer references as:
so we should heed those in the production of alt descriptions in each case. Notably, good alt text (quoting from the first link) should "[not] duplicate text that’s adjacent in the document or website", which is important because otherwise we could solve the problem by injecting the captions that exist for all images into the 'alt' text as a quick and simple solution - but actually, captions serve a different purpose to alt text so we should bare that distinction in mind.
Ideally we can have the original author/contributor and/or maker of each Figure image to approve any 'alt' description we can draft for it. If not, we can choose something that seems as sensible and intuitive as we (that is, anyone contributing to the PR to resolve this Issue) can gauge.
In practice, the alt text can be defined and added so that the make html build includes it, by defining it as the first parameter in the square brackets after an image is named (as documented e.g. in the Asciidoctor docs page here), e.g:
image::images/leap-second-timelines.svg[,70%,pdfwidth=50vw,align="center"]
becomes:
image::images/leap-second-timelines.svg["We've added some informative alt text here hooray",70%,pdfwidth=50vw,align="center"]
Benefits
Improving the digital accessibility and SEO potential of the Conventions document Figures could indirectly benefit the whole community, and above all in the former case directly benefit those with impairments or disabilities, esp. visual ones.
Status Quo
Alt text has not yet been considered for the CF Conventions document, and indeed most (if not all, TBC) images seem to not have anything meaningful defined for the image img element alt property.
Associated pull request
We don't have a full PR ready, but in the Hackathon session we set up a dedicated branch https://github.com/cf-convention/cf-conventions/tree/accessibility-main, to which will push alt text definitions (along with some other accessibility updates), with the aim to raise a PR of that branch once, at least, all alt text has been written and included (and tested as working!).
Detailed Proposal
n/a - all covered above.
Issue stemming from the CF Workshop 25 Hackathon session '(Digital) accessibility of the CF Convention document'. As chair of the session, I want to capture our agreed goals in formal Issues to track progress. @ChrisBarker-NOAA was also in the Hackathon and made good progress towards this one - thanks Chris (please do add to, clarify or query anything I say here to summarise if you wish)!
Title
Accessibility (& SEO): add informative 'alt' text to all figures
Moderator
n/a or TBC - likely not needed as this is an infrastructure change, and not controversial?
Moderator Status Review [last updated: YYYY-MM-DD]
n/a or TBC
Requirement Summary
Ensure all figures currently in the canonical CF Conventions document have considered, informative 'alt' (alternative) descriptions included for the HTML build (may also be possible to view in a PDF build depending on viewer). This means adding carefully-considered text to an 'alt' property for every image defined in the document.
Technical Proposal Summary
Digital accessibility good practice includes adding 'proper' descriptions of images, including figures and schematics, in the designated 'alt' element.
Alt text is a standard way to aid visually-impaired users to understand what an image is showing, which can be read by screen readers for example, and it is also beneficial because:
At present, as we discovered in the Hackathon, the AsciiDoc build of the canonical document injects text into 'alt' such that it is defined (and therefore we 'pass' tools that check that such an attribute exists) - but that text is simply the name of the image minus its extension, as defined in the 'images' directory. So, the 'alt' attribute is present on all Figures but not with values corresponding to intended use. For example, from use of browser developer tools ('inspect') we see that the image for Figure 4.1 has in its HTML
imgimage embed element the propertyalt="leap second timelines"which is the name of the image from the directory (images/leap-second-timelines.svg), and so on.Towards resolving this issue, we need to replace this default
alttext introduced by AsciiDoc with, for each Figure, an appropriate text description. Good practice for alt text is covered in such developer references as:so we should heed those in the production of alt descriptions in each case. Notably, good alt text (quoting from the first link) should "[not] duplicate text that’s adjacent in the document or website", which is important because otherwise we could solve the problem by injecting the captions that exist for all images into the 'alt' text as a quick and simple solution - but actually, captions serve a different purpose to alt text so we should bare that distinction in mind.
Ideally we can have the original author/contributor and/or maker of each Figure image to approve any 'alt' description we can draft for it. If not, we can choose something that seems as sensible and intuitive as we (that is, anyone contributing to the PR to resolve this Issue) can gauge.
In practice, the alt text can be defined and added so that the
make htmlbuild includes it, by defining it as the first parameter in the square brackets after an image is named (as documented e.g. in the Asciidoctor docs page here), e.g:image::images/leap-second-timelines.svg[,70%,pdfwidth=50vw,align="center"]becomes:
image::images/leap-second-timelines.svg["We've added some informative alt text here hooray",70%,pdfwidth=50vw,align="center"]Benefits
Improving the digital accessibility and SEO potential of the Conventions document Figures could indirectly benefit the whole community, and above all in the former case directly benefit those with impairments or disabilities, esp. visual ones.
Status Quo
Alt text has not yet been considered for the CF Conventions document, and indeed most (if not all, TBC) images seem to not have anything meaningful defined for the image
imgelementaltproperty.Associated pull request
We don't have a full PR ready, but in the Hackathon session we set up a dedicated branch https://github.com/cf-convention/cf-conventions/tree/accessibility-main, to which will push alt text definitions (along with some other accessibility updates), with the aim to raise a PR of that branch once, at least, all alt text has been written and included (and tested as working!).
Detailed Proposal
n/a - all covered above.