fixing links

[brownsarahm]

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)

[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-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               |  2 +-
 11-practice-teaching.md |  5 ++---
 14-checkout.md          |  2 +-
 15-carpentries.md       |  3 +--
 instructor-notes.md     |  4 ++--
 md5sum.txt              | 16 ++++++++--------
 9 files changed, 18 insertions(+), 21 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 2024-12-14 15:17:17 +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:

1. ...see [link][link] OR
2. ...see name-of-thing at [link][link] OR
3. ...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.

[ndporter]

Suggested change

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

Either "core values" needs added or "the" needs removed, whatever is more consistent with both accessiblity practices and other needs like ability to extract automatically to etherpads/etc.

[brownsarahm]

this one is actually hard, there is no longer a values page, but they need to read the values section on: https://carpentries.org/about-us/

(so we need to change the url too)

[ndporter]

We can use the section id to go right there, at least: https://carpentries.org/about-us/#our-values.

[ndporter]

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

1. ...see [link][link] OR
2. ...see name-of-thing at [link][link] OR
3. ...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]

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

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