Use clear link descriptions

[HonkingGoose]

There's no existing/similar bug report.

• I have searched the existing issues

This report is about a single actionable bug.

• I'm reporting a single actionable bug

This report is about the ProGit book, version 2, English language.

• This bug is not about a translation or old version

Bug covers book website/pdf

• I confirm the bug is about the book as found on the website/pdf

Problem is present in the Pro Git book on the website?

• This bug also affects the Pro Git book as published on the website.

Which version of the book is affected?

Source files

Describe the bug:

I reviewed PR #1708 where there was a link that was styled like this (it's fixed now 😉 ):

It can be found at https://github.com/Microsoft/Git-Credential-Manager-for-Windows[].

This will cause screenreaders to read out the link like this:

https colon slash slash github dot com slash gitcredentialmanager slash git hypen credential hyphen manager hypen for hypen windows

Nobody is going to understand what a link like that points to. 😉
So we should use the [] part of the AsciiDoctor link to give a name to the link.
This way humans can understand where they'll end up if they click on the link.

To be more accessible we should use link names instead of leaving them empty.

Steps to reproduce:

Do a grep search on the link pattern to find all hits.

Expected behavior:

Links should have human readable names.

Screenshots:

No response

Additional context:

I recommend you also read the MDN Web Docs, use clear link wording, as they have more helpful advice on how links should be named.

Device

No response

Operating system

No response

Browser/application + version

No response

[HonkingGoose]

@vtbassmatt can you maybe provide the grep search that you did to find other links that follow this "bad pattern"? That would help us fix this problem easier. 😉

[vtbassmatt]

Sure, though it's far from perfect 😅 I use VS Code as my editor. With the repo open as my workspace, I used the Search icon on the left bar, in regex mode, with the following patterns:

• http[^ ]*\[.+\] – finds instances of links which already have friendly names
• http[^ ]*\[\] – finds instances of nameless links (but there are false positives too, as it makes no attempt to filter out include:s and so on)

[HonkingGoose]

Thank you very much! 😄 ❤️