Guidance on display of external URLs in lessons

[ostephens]

Before Library Carpentry lessons formally joined the Carpentries, we had some discussion about the display of URLs in lessons (see data-lessons/library-openrefine-DEPRECATED#54)

tl/dr; should we include full URLs in the lesson visible to the users so they can be read both on screen and in print outs, or should they be done as hyperlinks with sensible link text instead of the full URL displayed

Guidance on this in the style guide would be appreciated

[maneesha]

Tagging @serahrono as I think this falls into accessibility work she is doing.

[bencomp]

I believe URLs are automatically shown in full when you print lesson content. (At least in the old infrastructure they were.)

So the "lemma" on links in the style guide applies, in my opinion: use meaningful text as link text, not URLs.

[maneesha]

@elletjies Do you want to keep this issue active in the new handbook? If it is no longer relevant, we can close this issue.

Note for now, would just be moving the issue to the new handbook. We don't need to create new resources or materials yet.

Asking you as this is accessibility related; not sure who the best person to ask for this would be.

[elletjies]

@maneesha could we move it to the new handbook so that CET can have a deeper discussion?

[maneesha]

@tobyhodges What should we do with this issue?

[tobyhodges]

It is best practice for web accessibility to use meaningful link text, and I believe the lessons and handbooks are read online much more often than they are printed out/downloaded as a PDF.

It looks like CSS can be used to add the URLs after links in the print version, as suggested by @bencomp above, so I will open an issue on varnish where we can discuss that further. Do you want to explore adding that to the CSS here too? If not, I suggest that the issue is closed.

[maneesha]

I don't know why I tagged Toby on this -- I think I meant to tag @elletjies

Anyhow, we did get an interesting solution from Toby, so I tried it out. See PR #290
The page displays as usual in the browser, but in the print out we see the urls for each link. Note this means that full URLs will always display when you print. It also displays relative URLs. Having them print optionally would require much more work and is beyond the scope of what we can do now.

Preview in browser:

Preview of printed page:

Also tagging @froggleston for input.

[elletjies]

@maneesha this is really great! Thank you @tobyhodges

[maneesha]

To follow up on this issue, I shared above what the printed page might look like on the home page, where the links are short and neat.

This is what it would look like on a page with long links:

This is what that same section would look like if links were not printed

I do not have expertise in accessibility but I do think that having those long links in the printed text (that no one would ever actually type out) makes it much more difficult to read.

We do not have the capacity right now to make this view optional - it either displays for every printed page or does not. (If anyone knows of an easier way to do this please share!)

You can test out what the printed view would look like by following the Netlify preview link in #290 and printing from there. (You don't actually need to print it; you can see it from your browser's print preview)

[bencomp]

Yes, those URLs are long and potentially hard to type without errors, but this is good to have. If I printed these pages and really found the URLs distracting, I can use a marker or pen to cross them out.

[elletjies]

@maneesha, I agree the links are quite distracting. I'm also not sure what a screen readers would read (if it does include the links) that would be problematic.

[bencomp]

@elletjies a screen reader can read the non-print version, I think, so although it may announce the link, I don't think it would always read out the full URL. Note that I have not used screen readers myself.

[maneesha]

I have only dabbled with screen readers and have not really used them myself, but I don't think that would be a concern as the screen reader would read the web page directly, not the printed version (unless it was reading a displayed pdf, which could be possible).

I would personally find those long urls very distracting on a printed page but I also don't often print things to read so I would not be a primary user of this feature.

The original issue as it was opened many years ago also seems to be intended for lessons, not necessarily the handbook, so that's another consideration.

[maneesha]

I discussed this with @froggleston
We agreed that while printed links are useful to have, this solution isn't great because it makes the text very difficult to read.
One option might be to include a list of links at the bottom of the printed page but we would need to explore how to make that work.
I am keeping this open but it is relatively low priority.