r-novice-inflammation icon indicating copy to clipboard operation
r-novice-inflammation copied to clipboard

Published 20 hours ago • verified publisher icon swcarpentry

convert "here" links to useful snippets

Open katrinleinweber opened this issue 6 years ago • 6 comments

Berkeley's Web Accessibility guide recommends against link texts like "Click here to read about our..." and suggests making them more descriptive: "..., read About Us". This helps screen reader users esp.

There are several instances of such links that could be converted accordingly.

katrinleinweber avatar Feb 14 '18 09:02 katrinleinweber

I have begun converting links in my own fork to meet these standards and will push them once they are done, but I have noticed that there are many glossary links, where a single word or concept (like String) has a link to the glossary. Is it suitable to leave these glossary links to stay as they are, or should they perhaps have an annotation? E.g. the String link might instead become the String (Glossary) link.

AnthonyDShaw avatar Jun 11 '18 03:06 AnthonyDShaw

Hi Anthony, and thanks for working on this :-)

I suggest to leave glossary links as they are for now. I'm looking forward to reviewing your PR with the new link texts. Feel free to open it already. Cheers!

katrinleinweber avatar Jun 11 '18 05:06 katrinleinweber

Hi @katrinleinweber , I was going to make a pull request, but after reading the guidelines "[SWC] would like substantial changes to be raised in an issue for input from maintainers before [I] work on a PR"

I am unsure if that counts in this context since I was going to make a pull request in response to your issue, but just in case I will instead link my own repository with the changes for commenting first. Or should I make a new issue instead?

https://github.com/AnthonyDShaw/r-novice-inflammation/tree/gh-pages/_episodes

AnthonyDShaw avatar Jun 12 '18 04:06 AnthonyDShaw

The guideline seems a bit too timid, IMHO. Updating some phrases are not "substantial changes". Even if they were, without seeing the actual change suggestions, a discussion about them is a bit moot. The guideline rather intends to protect contributors from working on changes that are not welcomed by the maintainers.

Since a PR has built-in review features, I find that most effective. We have too many issues already. ;-)

PS: I did add some comments to your commits, so we can compare how reviewing there works, vs. in a PR.

katrinleinweber avatar Jun 12 '18 05:06 katrinleinweber

Thanks for your work on this Anthony!

I just wanted to chime in and mention that it is the Rmd files that should be edited and committed, not markdown files directly, since the markdown is generated from the R markdown. I'll tweak the contribution guidelines a bit to make this (and PRs vs. issues) clearer.

diyadas avatar Jun 12 '18 09:06 diyadas

Whoa, sorry for missing that! I thought #359 would prevent this from happening again.

katrinleinweber avatar Jun 12 '18 12:06 katrinleinweber

I reviewed the code and couldn't find any occurences at this time.

Additionally, the new workbench infrastructure, and pegboard::validate_links() in particular, will now check that all links are associated with descriptive text:

https://github.com/carpentries/pegboard/blob/1bc5753e917d515c3d888ce6cc013c0a680eacfc/R/validate_links.R#L171-L188

Closing this issue. Thanks everyone for your work on this!

Bisaloo avatar Dec 16 '23 11:12 Bisaloo