dwyl / dwyl/contributing

Informative vs. Uniformative Link Text

Open
#119 0 comments 1 reaction 0 assignees View on GitHub
bug chore starter
Dominant language
No language data
Stars
91
Forks
9
PR merge metrics
No merged PRs in 30d

Description

"[this](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this)" is a _really_ unhelpful link text. 😕
It's bad for accessibility and SEO. 👎
Similarly [here]() or [link]() are exceptionally poor link text. 🙅
They tell me (and [vision impaired](https://en.wikipedia.org/wiki/Visual_impairment) people and **Google Bot**!) _nothing_ about the hyperlink. 🤷‍♂️

https://www.mtu.edu/accessibility/training/web/link-text/
![image](https://user-images.githubusercontent.com/194400/196665540-22ae7f9f-4718-4d40-bb78-aa80c8b1f8cd.png)

Remember your objective to _communicate_ with the person reading your documentation. 💬
Not force them to click/follow the link just to know what it is ... ⏳ 🤦‍♂️

With that in mind I usually just use the actual URL as the link text e.g: [github.com/dwyl/start-here](https://github.com/dwyl/start-here)
```sh
[github.com/dwyl/start-here](https://github.com/dwyl/start-here)
```
Or for brevity but not much loss of meaning: [dwyl/**start-here**](https://github.com/dwyl/start-here)
```sh
[dwyl/**start-here**](https://github.com/dwyl/start-here)
```
_Never_ [here](https://github.com/dwyl/start-here). _Ever_ ...!

> **Note**: I only do one [word](https://github.com/dwyl/english-words) links for [_effect_](https://youtu.be/QqSMohk0CV4) ... _never_ for actual work where we want to effectively communicate with people including those who are using a screen reader or the almighty Google Bot 🤖 praise be the algorithm. 🙌

# Todo

+ [ ] Add section to `README.md` including this advice so we can avoid having PRs with [here]() style links. 🙏

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.