Semantic Link Text

[nelsonic]

@dwyl we really appreciate getting contributions from the community. ❤️ ✅

But we often get contributions that end up requiring more work to "fix" than necessary...

I could link to many PRs where the (new) contributor has made an addition/change that takes more time for the reviewer to "remedy" (later) than if the reviewer simply closed the PR and applied the "correct" changes in the first place ... this is not the place/time to "rant" about people not reading/following the existing PR/Contributing guidelines, it is an opportunity to improve communication and learning for all future people/contributions!

This is not the fault of the person making the contribution, rather it's the my fault for not setting appropriate expectations i.e. communication fail. 😞

Not to "pick" on anyone in particular ... this happens from-time-to-time but I tend to "correct" it with PR comments instead of fixing it "systematically" with better instructions!

The Issue

Links to content where the link text does not give the reader any clue what the content is.

this just came up (again) in a PR and I think we need to "fix" (i.e. prevent) it. see:

The Downside(s) of Non-Semantic Link Text

There are several disadvantages to having non-semantic link text, here are the "Top 5 Reasons non-Semantic Link Text are Bad":

• Accessibility - Visually Impaired People have no idea what the content of the link is ... 😞 (yes, screen readers do read out the URL of the link, but it's way better if we include semantic/insightful text describing exactly what the content is either in the link text or alt text ...)
• Link Obfuscation - (Non Sight Impaired) People cannot see the what the link is or determine if it's relevant/useful without hovering over it.
• Mobile Unfriendly - a person on a mobile device cannot see the URL or infer the content of the link so it forces them to click links, load page(s) (wasting bandwidth) just to see if the content is relevant ... sure, the mobile user can "rely" on the content writer to an extent to not to link to useless/irrelevant things but how does the Mobile user know if "this" link is to a 20Mb PDF that is going to cost them $$$ to download on their connection? (it might be relevant but downloading it on a 2G internet connection would be super lame!)
• Search Engine Optimisation (SEO) - search engines cannot assess the relevance of the link or give "credit" to the content. 🕸 👎 see: https://moz.com/blog/the-anatomy-of-a-link
• Update Tracking - if the link text is "here", "example" or "this" it's not possible for people to see when the link gets updated.

Why Not Simply Use (Paste) the Full URL?

I prefer to simply paste the entire link in the body of the Markdown text especially when the URL is reasonably semantic / human readable.

For example: If this person had simply written "Screaming Architecture" I would probably not have clicked on it. But the fact that the article was written by "Uncle Bob" (who I briefly met @GRPN and highly respect!) immediately got my attention.

BTW: I'm a huge fan of the way links have a "Click Count" on Elixir Forum e.g: https://elixirforum.com/t/phoenix-v1-3-0-rc-0-released/3947

TODO

• [ ] Decide where we should put the instructions (@iteles thoughts?)

• [ ] Write clear beginner friendly instructions for people on how to create great links in:

  • [ ] Markdown files (which will/are rendered to HTML)
  • [ ] HTML should we be writing "Raw" HTML

• [ ] Link to Authoritative/Relevant "Background Reading" e.g:

  • Techniques for Web Content Accessibility Guidelines 1.0: https://www.w3.org/TR/WCAG10-HTML-TECHS/
  • Tips for Developers: https://www.sitepoint.com/15-rules-making-accessible-links
  • W3C Link Checker: https://validator.w3.org/checklink
  • Internal vs External HTML Links: https://www.khanacademy.org/computing/computer-programming/html-css/html-tags-continued/p/html-internal-links

Note: I think the "how to make a good link" instruction/guide could go in https://github.com/dwyl/learn-html5 or but 100% Open to Suggestions! 👍 Also, this raises another (un-related?) question: should we be writing "Raw" HTML? or should we be writing Markdown and converting it to AMP-compliant Accessible HTML?

[iteles]

I think that whether we put it in https://github.com/dwyl/learn-html5 or https://github.com/dwyl/learn-markdown, we can't really realistically expect that people will go through the whole tutorial if they think they already know those things, particularly if they are new to dwyl. It should certainly be in one of those anyway.

I would suggest that what we actually need is a checklist of things that reviewers will be looking out for (that checklist can link to the more content heavy learn-x repos) that we then add as a message to a PR template for all our repos.

[nelsonic]

@iteles a checklist for content reviewers is a really good idea! 😍 The reason we can expect people to go through the "whole tutorial" is because we are going to design the learning UX that way ... 😉 (as discussed in the park ages ago #LearningOrganisation ...)