fixing links - accessibility changes #1768

brownsarahm · 2024-12-14T15:16:16Z

I tried to resolve the conflicts on #1490 in a codespace, only to realized after I had gone through all of the conflicts that I could not push to the branch for the pr. I pushed to my own branch and I think the only choice I can do is make a new PR directly

Someone else should review this and then we can merge to get the accessibility updates.

(we could technically make a PR to @dpshelio 's branch, have him merge that and then merge #1490 but he said he is limited capacity, so I want to give us a path forward without him in the loop)

Co-authored-by: Karen Word <[email protected]>

github-actions · 2024-12-14T15:16:29Z

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-1768

The following changes were observed in the rendered markdown documents:

 01-welcome.md           |  2 +-
 02-practice-learning.md |  2 +-
 05-memory.md            |  3 +--
 09-eia.md               |  4 ++--
 11-practice-teaching.md |  7 +++----
 14-checkout.md          |  2 +-
 15-carpentries.md       |  7 +++----
 instructor-notes.md     |  4 ++--
 md5sum.txt              | 16 ++++++++--------
 9 files changed, 22 insertions(+), 25 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 2025-01-10 15:30:20 +0000

ndporter

In addition to inline suggestions, (template-md) and rmd version should be [template-md/rmd] to reference named link (round parentheses reference hard links). Git didn't like me putting suggestions on them.

More generally, should we use a consistent style, either:

...see [link][link] OR
...see name-of-thing at [link][link] OR
...see [name-of-thing][link]

I don't recall exactly where the discussion came down. Currently, these revisions are mostly a mix of 1 and 2. My understanding is 3 is best for accessibility because the surface text describes the link, but it can be an issue for copying and pasting exercises into etherpads. Either way, we should try to do them all the same.

episodes/09-eia.md

ndporter · 2024-12-17T18:56:49Z

More generally, should we use a consistent style, either:

...see [link][link] OR

...see name-of-thing at [link][link] OR

...see [name-of-thing][link]

I don't recall exactly where the discussion came down. Currently, these revisions are mostly a mix of 1 and 2. My understanding is 3 is best for accessibility because the surface text describes the link, but it can be an issue for copying and pasting exercises into etherpads. Either way, we should try to do them all the same.

@carpentries/core-team-curriculum what is the current guidance on link practice, given the constraints above about both accessibility and copy-paste readiness for pads?

tobyhodges · 2024-12-18T17:48:18Z

@carpentries/core-team-curriculum what is the current guidance on link practice, given the constraints above about both accessibility and copy-paste readiness for pads?

Indeed, accessibility best practice would be descriptive link text. But this will not play nicely with the etherpad generation. If that is a dealbreaker, I suggest either option 2 (see name-of-thing at [link][link]) or a redundant approach that makes the etherpad look nicer: see [name-of-thing][link] ([link][link]).

I marginally prefer the latter, while conceding that the redundancy will still be annoying for screen reader users. I leave the final decision up to the Maintainers.

brownsarahm · 2024-12-18T18:37:18Z

I think the latter approach has the additional advantage of being easy to switch to the only best practice option, if the template and/or etherpad tech changes

brownsarahm · 2025-01-10T15:10:12Z

I don't understand:

In addition to inline suggestions, (template-md) and rmd version should be [template-md/rmd] to reference named link (round parentheses reference hard links). Git didn't like me putting suggestions on them.

can you give the file(s) and line(s) of at least one occurence to help me parse what you are referring to (I only resolved the merge conflicts on this PR it is not really mostly my work)

tobyhodges · 2025-01-10T15:24:08Z

I think it's referring to lines 239 and 240 of 15-carpentries.md, which currently have malformed links.

brownsarahm · 2025-01-10T15:34:49Z

I have done the redundant thing discussed above now, I think this is ready to go.

Also I remembered that aria-hidden="true" css exists to hide the extra from screen readers, but I'm not sure how to do it. I think an actually ideal case would be that in parsing, the build tools would detect links inside of challenge blocks and insert at the end of the challenge block a list of the plain URLs in a list with this tag on it?

tobyhodges · 2025-01-10T15:47:26Z

Also I remembered that aria-hidden="true" css exists to hide the extra from screen readers, but I'm not sure how to do it. I think an actually ideal case would be that in parsing, the build tools would detect links inside of challenge blocks and insert at the end of the challenge block a list of the plain URLs in a list with this tag on it?

This is a nice idea. Please open an issue on https://github.com/carpentries/sandpaper to suggest it.

tobyhodges

Suggesting a few more polishes, but this seems mostly ready to go.

However, I think the instructors/checkout.md file can be removed? It looks like David's branch had that file in the instructors directory, where I think it might have lived in the past, but now it is only in learners/.

tobyhodges · 2025-01-10T15:50:11Z

episodes/09-eia.md

@@ -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 [ https://carpentries.org/about-us/#our-values][core-values]


Suggested change

1. Take a moment to read through the [ https://carpentries.org/about-us/#our-values][core-values]

1. Take a moment to read through [The Carpentries Core Values][core-values] [https://carpentries.org/about-us/#our-values][core-values]

tobyhodges · 2025-01-10T15:51:12Z

episodes/11-practice-teaching.md

 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](https://www.youtube.com/watch?v=jxgMVwQamO0)


Suggested change

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)

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](https://www.youtube.com/watch?v=jxgMVwQamO0)

tobyhodges · 2025-01-10T15:51:59Z

episodes/14-checkout.md

@@ -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](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).


Suggested change

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](checkout.md) [https://carpentries.github.io/instructor-training/checkout/index.html](checkout.md).

tobyhodges · 2025-01-10T15:54:57Z

instructors/checkout.md

+
+We recommend that contributions be directed to:
+
+- any [Data Carpentry]({{ site.dc_site }}/lessons/), [Library Carpentry]({{ site.lc_site }}/lessons/), or [Software Carpentry]({{ site.swc_site }}/lessons/) lesson


This line contains old Jekyll-style variable substitutions, which seems strange.

dpshelio and others added 5 commits February 17, 2023 18:08

Removes the "click here" like of links

554d73d

Updates plain links to hyperlink text

10696dd

make call-outlinks display url for copy-paste

3b36d08

Co-authored-by: Karen Word <[email protected]>

resolve conflict

11b5b5c

get updates from main

367f87a

brownsarahm requested review from ndporter and tobyhodges December 14, 2024 15:17

github-actions bot pushed a commit that referenced this pull request Dec 14, 2024

differences for PR #1768

768e39b

ndporter requested changes Dec 17, 2024

View reviewed changes

episodes/09-eia.md Outdated Show resolved Hide resolved

brownsarahm mentioned this pull request Jan 9, 2025

Basic accessibility changes #1490

Open

brownsarahm changed the title ~~fixing links~~ fixing links - accessibility changes Jan 10, 2025

update core values link for site reorg

69b0d2d

github-actions bot pushed a commit that referenced this pull request Jan 10, 2025

differences for PR #1768

021b31a

use redundant style

8c0a3e3

github-actions bot pushed a commit that referenced this pull request Jan 10, 2025

differences for PR #1768

66ff283

tobyhodges reviewed Jan 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fixing links - accessibility changes #1768

fixing links - accessibility changes #1768

brownsarahm commented Dec 14, 2024 •

edited

Loading

github-actions bot commented Dec 14, 2024 •

edited

Loading

ndporter left a comment

ndporter commented Dec 17, 2024

tobyhodges commented Dec 18, 2024 •

edited

Loading

brownsarahm commented Dec 18, 2024

brownsarahm commented Jan 10, 2025

tobyhodges commented Jan 10, 2025

brownsarahm commented Jan 10, 2025

tobyhodges commented Jan 10, 2025

tobyhodges left a comment

tobyhodges Jan 10, 2025

tobyhodges Jan 10, 2025

tobyhodges Jan 10, 2025

tobyhodges Jan 10, 2025

	1. Take a moment to read through the [ https://carpentries.org/about-us/#our-values][core-values]
	1. Take a moment to read through [The Carpentries Core Values][core-values] [https://carpentries.org/about-us/#our-values][core-values]

	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)
	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](https://www.youtube.com/watch?v=jxgMVwQamO0)

	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](checkout.md) [https://carpentries.github.io/instructor-training/checkout/index.html](checkout.md).


		We recommend that contributions be directed to:

		- any [Data Carpentry]({{ site.dc_site }}/lessons/), [Library Carpentry]({{ site.lc_site }}/lessons/), or [Software Carpentry]({{ site.swc_site }}/lessons/) lesson

fixing links - accessibility changes #1768

Are you sure you want to change the base?

fixing links - accessibility changes #1768

Conversation

brownsarahm commented Dec 14, 2024 • edited Loading

github-actions bot commented Dec 14, 2024 • edited Loading

Thank you!

Rendered Changes

ndporter left a comment

Choose a reason for hiding this comment

ndporter commented Dec 17, 2024

tobyhodges commented Dec 18, 2024 • edited Loading

brownsarahm commented Dec 18, 2024

brownsarahm commented Jan 10, 2025

tobyhodges commented Jan 10, 2025

brownsarahm commented Jan 10, 2025

tobyhodges commented Jan 10, 2025

tobyhodges left a comment

Choose a reason for hiding this comment

tobyhodges Jan 10, 2025

Choose a reason for hiding this comment

tobyhodges Jan 10, 2025

Choose a reason for hiding this comment

tobyhodges Jan 10, 2025

Choose a reason for hiding this comment

tobyhodges Jan 10, 2025

Choose a reason for hiding this comment

brownsarahm commented Dec 14, 2024 •

edited

Loading

github-actions bot commented Dec 14, 2024 •

edited

Loading

tobyhodges commented Dec 18, 2024 •

edited

Loading