[RFC] Add alt texts to images

[wouterj]

I suddenly realized we didn't offer any alt texts for any of our images/diagrams. This PR adds 2 alt texts, to gather feedback on both if we want this and how we are going to provide alt texts for our diagrams (which can be quite complex to explain in words).

I used https://medium.com/nightingale/writing-alt-text-for-data-visualization-2a218ef43f81 and https://sc.edu/about/offices_and_divisions/digital-accessibility/guides_tutorials/alternative_text/charts-diagrams/index.php as two examples to help me write this text (this is my first time properly thinking about alt texts).

[wouterj]

cc @symfony/diversity-champions and @symfony/team-symfony-docs I guess both of these teams have very relevant insights and knowledge about this :)

[lsmith77]

good catch!

it might actually make sense to run some automated a11y tools on regular intervals over the docs to catch stuff like this.

AFAIK “screenshot” is so generic that it can left off. if its a specific type of chart it makes sense to include it.

[zanbaldwin]

Agree with the automated a11y tools, but the alt text you’ve provided is good: detailed and succinct.

[wouterj]

Good idea with adding some automated testing here. We already use GitHub Actions to render the rst source to a complete HTML project, so I guess it shouldn't be too hard to find a tool that is able to lint the generated HTML? Is there any open source tool you're familiar with that works like this? (a quick google search mostly shows a11y tools that lint websites instead of source code?)

[artyuum]

Is there any open source tool you're familiar with that works like this? (a quick google search mostly shows a11y tools that lint websites instead of source code?)

@wouterj this tool seems to be able to validate local HTML files.

[wouterj]

This PR is now fully revisited and complete:

• All figures now contain an alt description
• Based on the feedback, I've made the alt descriptions pretty concise and instead favored tweaking the text surrounding the figure to create a better experience.
• I've added some documentation standards about alt descriptions, heavily inspired by https://www.med.unc.edu/webguide/accessibility/alt-text/
• While going over all diagrams, I've found some very old and inconsistent diagram styles. I've upgraded all of them to our own diagram style and fixed some exporting bugs for other diagrams.

[wouterj]

Some of the SVG's look like they have white backgrounds instead of transparent - is that correct?

Yes, all of them should have white backgrounds. I'm not a dark theme user myself, but it seems like we do not automatically invert diagram colors when switching to the dark theme. This means that without the white background, diagrams will be unreadable because it's black on black.

[wouterj]

Unfortunately, multi line options aren't supported by the Doctrine rst-parser 0.5. I've contributed this to 0.6, but given it includes a BC break I don't think we can backport the fix to 0.5. I think effort is better spend to work on the phpDocumentor parser, so I think we'll not upgrade to 0.6 any time soon (note that this is also not officially released yet, as the Doctrine team also focuses on the new parser).

TL;DR: all alt text must be on a single line, bypassing our soft 72 character limit. I guess this will help us push towards concise descriptions :wink:

[sstok]

I don't know what a .dia file is, but it seems there are some .dia.autosave files, is this correct?

[wouterj]

Thanks for the reviews! Those autosave files were definitely not intended, I've removed them.

Merge up was without a conflict (surprisingly) :smiley:

[OskarStark]

Thank you 🙏