Basic accessibility changes

[dpshelio]

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

[github-actions]

Thank you!

Thank you for your pull request 😃

🤖 This automated message can help you check the rendered files in your submission for clarity. If you have any questions, please feel free to open an issue in {sandpaper}.

If you have files that automatically render output (e.g. R Markdown), then you should check for the following:

• 🎯 correct output
• 🖼️ correct figures
• ❓ new warnings
• ‼️ new errors

Rendered Changes

🔍 Inspect the changes: https://github.com/carpentries/instructor-training/compare/md-outputs..md-outputs-PR-1490

The following changes were observed in the rendered markdown documents:

 01-welcome.md           | 10 +++++-----
 02-practice-learning.md |  2 +-
 05-memory.md            |  3 +--
 09-eia.md               |  2 +-
 11-practice-teaching.md |  5 ++---
 14-checkout.md          |  6 +++---
 15-carpentries.md       |  3 +--
 17-live.md              |  4 ++--
 20-performance.md       |  6 +++---
 21-management.md        | 12 ++++++------
 checkout.md             |  6 +++---
 instructor-notes.md     |  6 +++---
 md5sum.txt              | 24 ++++++++++++------------
 13 files changed, 43 insertions(+), 46 deletions(-)

What does this mean?

If you have source files that require output and figures to be generated (e.g. R Markdown), then it is important to make sure the generated figures and output are reproducible.

This output provides a way for you to inspect the output in a diff-friendly manner so that it's easy to see the changes that occur due to new software versions or randomisation.

⏱️ Updated at 2023-02-17 18:28:15 +0000

[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]

Suggested change

	concepts involved? How are those concepts related? (Note: if you would like to try out an online tool for this exercise, visit [excalidraw](https://excalidraw.com).)
	concepts involved? How are those concepts related? (Note: if you would like to try out an online tool for this exercise, visit [https://excalidraw.com](https://excalidraw.com).)

[karenword]

Suggested change

	This [website implements a short test of working memory][memory-test].
	This website implements a short test of working memory [https://miku.github.io/activememory/][memory-test].

[karenword]

Suggested change

	1. Take a moment to read through the [Core Values][core-values]
	1. Take a moment to read through the [https://carpentries.org/values/][core-values]

[karenword]

Suggested change

	Watch [this example teaching video][bad-teaching-video] as a group
	Watch this example teaching video as a group [https://www.youtube.com/watch?v=-ApVt04rB4U][bad-teaching-video]

[karenword]

Suggested change

	Note: there is a version of [this video with subtitles in both Spanish and English](https://www.youtube.com/watch?v=jxgMVwQamO0)
	Note: there is a version of this video with subtitles in both Spanish and English: [https://www.youtube.com/watch?v=jxgMVwQamO0](https://www.youtube.com/watch?v=jxgMVwQamO0)

[karenword]

Suggested change

	In small groups, read and discuss one of the three [checkout procedures described on this page](checkout.md).
	In small groups, read and discuss one of the three checkout procedures described on this page: [https://carpentries.github.io/instructor-training/checkout/index.html](checkout.md).

[karenword]

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

[karenword]

Suggested change

	Visit the [discussion Etherpad to sign up](https://pad.carpentries.org/community-discussions) for a session.
	Visit the discussion Etherpad to sign up: [https://pad.carpentries.org/community-discussions](https://pad.carpentries.org/community-discussions) for a session.

[karenword]

Suggested change

	Take a couple of minutes to sign up for [The Carpentries channels][connect-page] you want to stay involved with.
	Take a couple of minutes to sign up for The Carpentries channels you want to stay involved with: [https://carpentries.org/connect/][connect-page]

[karenword]

Suggested change

	Watch this first [participatory live coding demo video][live-coding-bad]
	and this [second demo video][live-coding-good]
	Watch this first participatory live coding demo video: [https://youtu.be/bXxBeNkKmJE][live-coding-bad]
	and this second demo video: [https://youtu.be/SkPmwe\_WjeY][live-coding-good]

[karenword]

Suggested change

	1. Before splitting into groups, read the [rubric that is given to Instructor Trainers](demos_rubric.md)
	as a suggested framework for evaluating the online teaching demonstration sessions that are part of Instructor checkout.
	(Note: demos are not scored, so this rubric is for
	1. Before splitting into groups, read the rubric that is given to Instructor Trainers
	as a suggested framework for evaluating the online teaching demonstration sessions that are part of Instructor checkout.
	[https://carpentries.github.io/instructor-training/demos\_rubric/](demos_rubric.md).
	(Note: demos are not scored, so this rubric is for

[karenword]

Suggested change

	1) Take 5 minutes to read through the [Code of Conduct Incident Response Guidelines](https://docs.carpentries.org/topic_folders/policies/incident-response.html)
	1) Take 5 minutes to read through the Code of Conduct Incident Response Guidelines: [https://docs.carpentries.org/topic\_folders/policies/incident-response.html](https://docs.carpentries.org/topic_folders/policies/incident-response.html)

[karenword]

Suggested change

	2) Discuss what you have read in small groups. As questions arise, you may wish to refer to [our complete Code of Conduct section in The Carpentries Handbook](https://docs.carpentries.org/topic_folders/policies/index_coc.html)
	2) Discuss what you have read in small groups. As questions arise, you may wish to refer to our complete Code of Conduct section in The Carpentries Handbook:
	[https://docs.carpentries.org/topic\_folders/policies/index\_coc.html](https://docs.carpentries.org/topic_folders/policies/index_coc.html) or to the Transparency Reports released by The Carpentries Code of Conduct Committee: [https://github.com/carpentries/executive-council-info/tree/master/code-of-conduct-transparency-reports](https://github.com/carpentries/executive-council-info/tree/master/code-of-conduct-transparency-reports)(https://docs.carpentries.org/topic_folders/policies/index_coc.html)

[karenword]

Suggested change

	Go to the [workshop template repository](https://github.com/carpentries/workshop-template)
	Go to the workshop template repository: [https://github.com/carpentries/workshop-template](https://github.com/carpentries/workshop-template)

[karenword]

Suggested change

	remaining, have a look at the websites for [upcoming Carpentries workshops](https://carpentries.org/upcoming_workshops/)
	remaining, have a look at the websites for upcoming Carpentries workshops on our website: [https://carpentries.org/upcoming\_workshops/](https://carpentries.org/upcoming_workshops/)

[karenword]

Suggested change

	[instructions to bypass your browser cache](https://en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache).
	instructions to bypass your browser cache: [https://en.wikipedia.org/wiki/Wikipedia:Bypass\_your\_cache](https://en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache).