Basic accessibility changes

[dpshelio]

• Removes links saying here. As they are not meanigful for screen readers
• Converts plain links to meaningful hyperlinks

[github-actions]

🆗 Pre-flight checks passed 😃

This pull request has been checked and contains no modified workflow files, spoofing, or invalid commits.

Results of any additional workflows will appear here when they are done.

[brownsarahm]

i think this is like this in order to help the etherpad transfer? @karenword

[karenword]

yes thanks for the catch @brownsarahm -- all links in callouts are written out in the text to make them easier to copy/paste into the Etherpad.

[ndporter]

Any changes here should be mirrored on other exercises with links like the concept map exercise and working memory exercise.

@brownsarahm I'd guess you're right about it being for etherpad purposes since the same link is under natural text in another part of this lesson.

I can think of a couple of solutions which might improve the accessibility here without making it much harder for trainers:

1. Make the change everywhere but emphasize in the main trainers/instructor notes page and through communication with trainers that there is an instructor training etherpad template that exercises/notes can be copy/pasted from. This would also require ensuring we keep up changes on that etherpad if exercises/headings are updated. (As an aside that doesn't directly apply in this repo, it might be worth copying that template to a fixed plaintext file somewhere, since it's not unusual for trainers to accidentally edit the template instead of their copy).
2. Make the change everywhere and add in-line instructor notes with copy-paste-ready versions in the instructor view.

[brownsarahm]

Does the etherpad exporter work at all in the workbench? could a new version of that help?

I prefer 2 to 1 but it is still a potential maintenance hazard...

[ndporter]

Etherpad exporter? I don't think I knew something like that existed. I assumed someone had just gone through and copied the headings and questions into the template pad.

[karenword]

AFAIK @zkamvar was unable to port the etherpad exporter over to the workbench, though he did put some thought into trying. I didn't want it to hold us up for beta participation, so we went ahead without it. It would be cool to get it back some day (and maybe have it better optimized to feature content in a more nuanced way than headers/keypoints). Even without it, though, I believe some Trainers do occasionally copy-paste from the curriculum when they teach. It would be fine to have those in the notes, though, if people prefer.

[zkamvar]

AFAIK @zkamvar was unable to port the etherpad exporter over to the workbench, though he did put some thought into trying.

This is correct. It was a neat feature, but it required a fun mix of JavaScript and liquid templating... and we do not use the latter in The Workbench to make life simpler.

It would be cool to get it back some day (and maybe have it better optimized to feature content in a more nuanced way than headers/keypoints).

This also depends on how long we continue to use Etherpad as the default collaborative notes tool. It's beginning to show its age and there are accessibility issues with its default interface.

[karenword]

This also depends on how long we continue to use Etherpad as the default collaborative notes tool. It's beginning to show its age and there are accessibility issues with its default interface.

Not exactly -- the exporter could be used for any collaborative document. I think it was just titled Etherpad because it was intended for that purpose. The appeal was that it could theoretically eliminate the need to maintain a separate template for that collaborative document (but we still maintain one anyway).

[zkamvar]

Not exactly -- the exporter could be used for any collaborative document. I think it was just titled Etherpad because it was intended for that purpose. The appeal was that it could theoretically eliminate the need to maintain a separate template for that collaborative document (but we still maintain one anyway).

(I should really remember to re-read what I write after edits). My bad. What I was trying to convey is that the etherpad exporter was very specific to etherpad's specific HTML quirks (to the tune of ~150 lines of JavaScript fiddling) such that developing something specific to Etherpad if we are going to move away from it would be sunk time.

FWIW, I have a code handout document in the works, and it shouldn't be to difficult for me to extract specific sections from the markdown for insertion into something like CodiMD or even a GitHub discussion.

[karenword]

I'd really like to incorporate the changes that improve descriptive text, but I think we should preserve the links written out in activity callouts because this allows copying and pasting instructions directly from the curriculum into a collaborative document.

[tobyhodges]

It would be great to be able to merge in the improvements to add more descriptive link texts, even if you want to leave the bare URLs in callouts and exercises. @dpshelio are you willing to adjust this PR to do that? If not, I am happy to make the changes on a new branch.

FWIW, my vote would be for including a descriptive link in callouts and exercises, followed by the bare URL afterwards, e.g.

Before splitting into groups, 
read [the rubric for evaluating teaching demonstrations](https://carpentries.github.io/instructor-training/demos_rubric.html) 
that is given to Instructor Trainers as a suggested framework for the online demonstration sessions that are part of Instructor checkout
(https://carpentries.github.io/instructor-training/demos_rubric.html). 
(Note: demos are not scored, so this rubric is for advisory purposes only.) 
What questions do you have?

Before splitting into groups, read the rubric for evaluating teaching demonstrations that is given to Instructor Trainers as a suggested framework for the online demonstration sessions that are part of Instructor checkout (https://carpentries.github.io/instructor-training/demos_rubric.html). (Note: demos are not scored, so this rubric is for advisory purposes only.) What questions do you have?

Not great for screen reader users to have to navigate through duplicate links, but at least they get one with descriptive text.

[brownsarahm]

i like the compromise of the both versions. I definitely do not want to prevent the better links, but I did want to flag the possible unintended consequence to make sure we have a way to deal with that.

[zkamvar]

For what it's worth, it may also be possible to add some JS/CSS that will allow people to copy a link as markdown-formatted (github allows this, but only within GitHub) using the Clipboard API (see https://developer.mozilla.org/en-US/docs/Web/API/Clipboard and https://jcarroll.com.au/2023/06/02/hyperlink-annotations-in-javascript-and-css/ for link formatting examples), but of course, this all depends on the capacity to be able to implement and test it.

(note: all of this would exist in {varnish})

[tobyhodges]

For what it's worth, it may also be possible to add some JS/CSS that will allow people to copy a link as markdown-formatted

I like the sound of this but I am not sure that Markdown-formatted links will be nice for pasting into the Etherpad, while that is still our shared notes platform of choice.

[brownsarahm]

I like the sound of this but I am not sure that Markdown-formatted links will be nice for pasting into the Etherpad, while that is still our shared notes platform of choice.

Unless there is an infrastructure (as opposed to habit) reason to prefer etherpad over codimd maybe this is a reason to push a leap to codimd?

[ndporter]

I like the sound of this but I am not sure that Markdown-formatted links will be nice for pasting into the Etherpad, while that is still our shared notes platform of choice.

Unless there is an infrastructure (as opposed to habit) reason to prefer etherpad over codimd maybe this is a reason to push a leap to codimd?

Codimd does present some additional challenges and cognitive load in a couple of ways:

1. The WYSIWYG tools are available but only connected to the "code" screen (e.g. you still have to type in the screen that doesn't look formatted
2. Using the "both" display in codi allows editing and viewing but they are separate, meaning people need to scan back and forth to see the efffects of what they're doing (and also need to use more screen real estate to effectively use it than an etherpad.
3. Ultimately even with the various shims and wysiwyg tools in codi, the code itself builds in markdown, which is useful but not necessarily welcoming to everyone.

I'd also want to run codimd past an accessibility review before rolling it out beyond leadership/maintainers/etc.

[karenword]

re CodiMD vs Etherpad: while I think there are many workshops in which the cognitive load associated with learning and using CodiMD is worthwhile, I do not think that Instructor Training is among them. While The Carpentries supports both CodiMD and Etherpad instances, currently the predominant tools used for this training are Etherpad and Google Docs, and I do not foresee that changing. We also currently commit to maintaining only one document template, and that is on Etherpad.

If there is a strong desire to change our recommendation and support for a collaborative document platform, I think that should probably be taken up by Trainers Leadership (our CAC).

[karenword]

suggesting to revert all remaining links in call-outs to preserve copy/paste friendly text for Trainers.

[anenadic]

I am just going through the instructor training material in preparation for a workshop tomorrow and have noticed the accessibility issues that @dpshelio fixed in this PR - just wanted to give a 👍 for this PR to be merged.