[Tutorial A11y]: Issues reading Make It So Tutorial using VoiceOver, clicking on tutorial steps to show related code blocks is inaccessible

[robin24]

First off, many thanks to you for having created this absolutely great tutorial!

I am a fully blind developer, and wanted to get started on learning how to integrate Firebase with SwiftUI. Sadly there don't seem to be too many detailed text tutorials out there, most content only exists in video format which is hard for me to follow.

As a MacOS user, I'm using VoiceOver, the screenreader built into all of Apple's platforms.
While the Make It So tutorial page can be navigated and read with VoiceOver without any issues, there unfortunately is a major accessibility bug when it comes to showing the code snippets for the various tutorial steps.
From what I understand, normally a user would click on (or maybe just hover over?) each of the steps that have associated code blocks, which would then show the code block associated with that step.
Unfortunately, it seems like some markup might be missing that would allow a screenreader like VoiceOver to detect these as clickable elements, basically making it impossible to show or hide the associated code blocks.

If you could kindly look into this when you have some time, I'd super greatly appreciate that. Like I said, based on my own findings this appears to be the most in-depth text tutorial on getting up to speed with Firebase and SwiftUI, and I'd love to go through the experience of building the Make It So app from scratch.

In case fixing the tutorial page requires too much work or isn't feasible for any reason, I'd also be happy about a text version of the tutorial.

Thanks, and keep up the great work!

[peterfriese]

Hey @robin24, thanks so much for the kind words. I really appreciate it!

I'm sorry to hear that there are accessibility issues with the tutorial. Have you tried Apple's tutorials? Do they have the same issue? If not, then there is definitely a way to fix this. It'll just take some time...

[robin24]

Hey @peterfriese,

Thanks for your response, you're more than welcome!

Now that you've mentioned Apple's tutorials, I remembered This one for the Swift OpenAPI Generator.
This seems to have a very similar layout to your tutorial, and actually happens to have the exact same accessibility issue...
So now I'm curious, what's the name of the underlying tool that is used for page generation here? Perhaps it would be a good idea to open an issue about this in that project's repo for an upstream fix.

[peterfriese]

Hi @robin24 - I've reached out to the DocC team, and they confirmed this is an issue in the renderer.

This is now being tracked at swiftlang/swift-docc-render#949

Once this has been resolved, it should be sufficient to rebuild the tutorial to get proper A11y support.

Thanks again for raising this!

[robin24]

Hey @peterfriese,

Thanks so much for taking the time to reach out to them with the issue, super greatly appreciated!
Hopefully this should improve lots of other doc pages / tutorials as well once there is a fix.
Meanwhile, I've found that saving individual tutorial pages to disk and then reading them with TextMate is quite doable as a workaround :-).