-
-
Notifications
You must be signed in to change notification settings - Fork 289
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Basic accessibility changes #1490
base: main
Are you sure you want to change the base?
Conversation
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:
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:
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 |
@@ -55,7 +55,7 @@ things that we do, things that we are, and things that we champion. Many of thes | |||
|
|||
## Discuss The Carpentries Core Values | |||
|
|||
1. Take a moment to read through the Core Values on this page: [https://carpentries.org/values/][core-values] | |||
1. Take a moment to read through the [Core Values][core-values] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i think this is like this in order to help the etherpad transfer? @karenword
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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:
|
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... |
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. |
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. |
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.
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). |
(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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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?
Not great for screen reader users to have to navigate through duplicate links, but at least they get one with descriptive text. |
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. |
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}) |
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:
I'd also want to run codimd past an accessibility review before rolling it out beyond leadership/maintainers/etc. |
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). |
@@ -194,7 +194,7 @@ perhaps illustrated as: | |||
|
|||
1) On a piece of paper, draw a simplified concept map of the same concept you discussed in the last activity, but this time without the analogy. | |||
What are 3-4 core | |||
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) .) | |||
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).) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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).) |
@@ -56,8 +56,7 @@ frequent formative assessment is important. | |||
|
|||
## Test Your Working Memory | |||
|
|||
This website implements a short test of working memory: | |||
[https://miku.github.io/activememory/][memory-test] | |||
This [website implements a short test of working memory][memory-test]. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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]. |
@@ -55,7 +55,7 @@ things that we do, things that we are, and things that we champion. Many of thes | |||
|
|||
## Discuss The Carpentries Core Values | |||
|
|||
1. Take a moment to read through the Core Values on this page: [https://carpentries.org/values/][core-values] | |||
1. Take a moment to read through the [Core Values][core-values] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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] |
@@ -173,15 +173,14 @@ it is OK to remind yourself: | |||
|
|||
We will start by observing some examples of teaching and providing some feedback. | |||
|
|||
Watch this example teaching video as a group | |||
Watch [this example teaching video][bad-teaching-video] as a group |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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] |
Put your feedback in the Etherpad. | ||
Organize your feedback along two axes: | ||
positive vs. opportunities for growth (sometimes called "negative") | ||
and content (what was said) vs. presentation (how it was said). | ||
|
||
Note: there is a version of this video with subtitles in both Spanish and English here: [https://www.youtube.com/watch?v=jxgMVwQamO0](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) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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) |
@@ -37,7 +37,7 @@ Extensions may be granted for any reason up to 1 year from your training date. | |||
|
|||
## Be The Expert: Checkout Q \& A | |||
|
|||
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) | |||
In small groups, read and discuss one of the three [checkout procedures described on this page](checkout.md). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
suggesting to revert all remaining links in call-outs to preserve copy/paste friendly text for Trainers.
@@ -52,12 +52,12 @@ This exercise should take about 10 minutes. | |||
|
|||
## Schedule a Discussion or Demo | |||
|
|||
Visit the discussion Etherpad to sign up for a session: [https://pad.carpentries.org/community-discussions](https://pad.carpentries.org/community-discussions) | |||
Visit the [discussion Etherpad to sign up](https://pad.carpentries.org/community-discussions) for a session. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
@@ -295,8 +295,7 @@ Want to **join meetings** (to meet new people or listen in)? | |||
|
|||
## Get Connected | |||
|
|||
Take a couple of minutes to sign up for The Carpentries channels you want to stay involved with on this page: | |||
[https://carpentries.org/connect/][connect-page] | |||
Take a couple of minutes to sign up for [The Carpentries channels][connect-page] you want to stay involved with. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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] |
Watch this first [participatory live coding demo video][live-coding-bad] | ||
and this [second demo video][live-coding-good] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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] |
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 |
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) | ||
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) | ||
1) Take 5 minutes to read through the [Code of Conduct Incident Response Guidelines](https://docs.carpentries.org/topic_folders/policies/incident-response.html) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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) |
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) | ||
1) Take 5 minutes to read through the [Code of Conduct Incident Response Guidelines](https://docs.carpentries.org/topic_folders/policies/incident-response.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) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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) |
@@ -396,13 +396,13 @@ instructions for setting them up. | |||
For this activity, your Trainer will put you in groups, but you may choose whether to work together or independently. | |||
If you work independently, you can still use your group as a resource to ask questions as they emerge. | |||
|
|||
Go to the workshop template repository: [https://github.com/carpentries/workshop-template](https://github.com/carpentries/workshop-template) | |||
Go to the [workshop template repository](https://github.com/carpentries/workshop-template) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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) |
|
||
- If you have a GitHub account (or don't mind creating one) and are comfortable doing so, | ||
follow the directions to begin creating a workshop website using your local location and today's date. | ||
|
||
- Alternatively, have a look at the video tutorial linked on the instructions page. With any time | ||
remaining, have a look at the websites for upcoming Carpentries workshops on our website: [https://carpentries.org/upcoming\_workshops/](https://carpentries.org/upcoming_workshops/) | ||
remaining, have a look at the websites for [upcoming Carpentries workshops](https://carpentries.org/upcoming_workshops/) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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/) |
@@ -413,7 +413,7 @@ Note: Sometimes web browsers will cache the workshop webpage, so when | |||
you make changes in GitHub, they do not show up on the workshop webpage | |||
immediately. Two ways to avoid this are to use a "private" or | |||
"incognito" mode in your web browser or by following these | |||
instructions to bypass your browser cache: [https://en.wikipedia.org/wiki/Wikipedia:Bypass\_your\_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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[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). |
here
. As they are not meanigful for screen readers