link style

[evanwill]

Looking though the lesson I noticed that links to additional resources are given as full URLs not hyperlinks, for example:

Full documentation for the GREL is available at https://github.com/OpenRefine/OpenRefine/wiki/Google-refine-expression-language.

Rather than, say GREL documentation. Software carpentry typically uses hyperlinks, not full URLs, which is a bit easier to read. Is there a reason for the current style, or could we switch it up?

[weaverbel]

@evanwill I don't think there has been a discussion about which way to go - I think this is just how it has happened. I'll post the link to the issue in the chat room and see what people think.

[drjwbaker]

I'm in favour of full citations where possible.

[richyvk]

Hyperlinks satisfy the semantic web geek in me. They are easier to read.

[weaverbel]

I am pro full links as well (though I used hyperlinks on the contrib and readme files I just updated for the Mozilla sprint.)

[ostephens]

I think we've got two in favour of fully written out URLs and two in favour of using a hidden hyperlink.

I'm reasonably neutral on this, but I'm probably responsible for the fully written out URLs that are there already, so I guess that shows I'm biased in that direction!

Any more views?

[evanwill]

I typically use full URLs in footnotes and references at the bottom, but it seems distracting in the lesson text, making it much less compact. I also see it as a consistency issue since the other Software, Data, and Library carpentry lessons use regular hyperlinks, not full URLs in the lesson text.

[evanwill]

Here is the Software Carpentry lesson template example for reference: http://swcarpentry.github.io/lesson-example/

[ostephens]

@evanwill I understand but opinion seems to be divided here, and I found an example of a full URL being used in the first SWC lesson I looked at https://github.com/swcarpentry/r-novice-gapminder/blob/gh-pages/_episodes/01-rstudio-intro.md

[remerjohnson]

I hate to say "it depends", but sometimes a full address can be incredibly nasty and really pays to put into a shortened form. I also think that encourages more linking (like linking to an ambiguous/esoteric term's Wikipedia page).

I also like footnote-style linking, which is also real nice to write in Markdown, but I know some people do not like that style.

[evanwill]

@ostephens there is only one full URL in that whole lesson, in a block quote:

Further reading: http://floating-point-gui.de/

It's probably an oversight in that particular lesson, and in general the hyperlink text should be meaningful, so the way that link is written wouldn't work well. For example, Further reading is not so good, but "Learn more at The Floating-Point Guide" would be better.

As I said earlier, there is a lot of full URLs in the references / resources sections, but not in the lesson text, for example: http://www.datacarpentry.org/cloud-genomics/

[ostephens]

It feels like we're spending more energy on this than it deserves. If someone submits a PR with these converted to hyperlinks I'll review & accept unless good reason not to

On 27 Apr 2017, at 21:34, EvanWill notifications@github.com wrote:

@ostephens there is only one full URL in that whole lesson, in a block quote:

Further reading: http://floating-point-gui.de/

It's probably an oversight in that particular lesson, and in general the hyperlink text should be meaningful, so the way that link is written wouldn't work well. For example, Further reading is not so good, but "Learn more at The Floating-Point Guide" would be better.

As I said earlier, there is a lot of full URLs in the references / resources sections, but not in the lesson text, for example: http://www.datacarpentry.org/cloud-genomics/

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[ostephens]

Sorry, that was a bit abrupt/rude. What I meant to say was: I'm absolutely ok with using hyperlinks, and I accept that this makes for nicer reading etc. And if someone would make an appropriate pull request then I'm happy to review & merge

Sorry for being a bit short in my previous reply

[ccronje]

URLs are useful for hard copies - colleagues like to have a hard copy by their side during a workshop and have suggested a handout for each lesson would be good (perhaps we could look at this for Moz Sprint?). But wrt this thread, a compromise may be hyperlinks in-text plus footnotes for full URLs. If that is overkill, I'd welcome a lesson handout summary with key URLs.

[evanwill]

Sounds good. I hope to do some work on it during the June 1 sprint. I just did a workshop and wrote another tutorial on it, so it's on my mind.

[weaverbel]

I think an example of ugly and unreadable URLs are those, say, for a Google Doc - I tend to use URL shorteners for those to make them memorable. The reason I like spelled out URLs is I have a quasi-photographic memory, so if I've seen a URL, I can recall it. Obviously that doesn't work with hyperlinks. Starting to wonder if we need to develop a Style Guide????