fixing links - accessibility changes

[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               |  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-14 16:41:32 +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]

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

[brownsarahm]

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]

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

[brownsarahm]

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]

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]

Thanks @brownsarahm 🙌

[ndporter]

Looks good to me.

[ndporter]

Note on this: there are some places with mid-line links where this technique starts to look pretty messy like:

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/policies/coc/ 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

I don't think this PR includes any of those, but we should probably set these up so there are line breaks after any link that's spelled out like this.

[brownsarahm]

Do you want to make those changes here or open a new issue for them?

[ndporter]

Do you want to make those changes here or open a new issue for them?

I suppose I should open a new issue. Maybe I'll try later today to go through the whole AIO and look for any of those. But let's get this one merged as is (once any other reviews are complete).