25

There are questions or answers where the original author adds links with the following format:

Link to documentation: https://example.com

Code example: https://www.google.com

Then someone suggests to edit them to:

Link to documentation

Code example

Should this type of suggested edit be approved if nothing else is changed in the post other than the link format? Personally I prefer being able to see the full URL of the link I'm clicking at first glance.

Here is an actual example I stumbled upon:

Original:

We want to keep the first 3 rules and we can do this with class="d-flex flex-wrap" (see https://getbootstrap.com/docs/4.1/utilities/flex/):

Edited:

We want to keep the first 3 rules and we can do this with class="d-flex flex-wrap" (see here):

4
  • 2
    These really aren’t good link titles - especially the first since it removes the literal link. Are the real examples you are concerned about equally unsuitable? Commented Sep 21, 2022 at 15:09
  • 7
    "Code example" is a little ambiguous, but at least for the documentation links, I think it's generally more of an improvement if the links are actively incorporated into the body text, rather than being standalone "link here" text. E.g. instead of "link to documentation", editors/ authors should try to incorporate it more naturally: "I found that the documentation details how this method works, and it goes like this..."
    – zcoop98
    Commented Sep 21, 2022 at 15:19
  • I agree and I would write this as: 'We want to keep the first 3 rules and we can do this with flex-wrap: <code here>' where flex-wrap is a link to getbootstrap.com/docs/4.1/utilities/flex/#wrap Commented Sep 23, 2022 at 11:17
  • 1
    In general you probably shouldn't trust that the first style shows the right link, see here: https://meta.stackoverflow.com/question/420...
    – Izkata
    Commented Sep 23, 2022 at 21:35

2 Answers 2

64

Formatting links like this is a major improvement for some users. Consider the difference:

aitch tee tee pee ess colon slash slash double you double you double you dot Google dot com link

And

Code example link

This is how screen readers like Voiceover read links. Which do you prefer? (And this is a very short link!)

Visual users are better at scanning, but still get some benefit from formatted links. It also looks professional to have formatted links.

Important! Make sure the link text is informative:

  • "Link" and "see here" are bad. This text says nothing about any link.
  • "Code example" and "documentation" are only slightly better. It specifies what the link is a little.
  • "Bootstrap 4 Flex documentation" or "Codepen showing select() performance" would be the best. With distinctive link text like this, you know exactly what to expect before visiting the page.

If the edit replaces a bare link with an informative formatted link, approve it.

(There are some situations where you would want to see the bare URL, such as API call examples, but those are the minority, and people don't tend to suggest edits to format those.)

See also Yale's accessibility article on links

9
  • 14
    I never shy away from making minor (but helpful) edits since I have high enough reputation to have them take effect immediately, but I've found that rarely are links presented so poorly that they need to be edited (for example, the real example OP has provided doesn't look that bad). However, this answer makes a good argument for formatting links regardless of their presentation in the name of accessibility. I'll keep that in mind moving forward.
    – Kraigolas
    Commented Sep 21, 2022 at 19:58
  • So there are users who use voiceover software and getting blocks of code dictated by it is fine, but links are cumbersome? Mhh ... ok.
    – Tom
    Commented Sep 22, 2022 at 10:49
  • 4
    @Tom How code blocks are read depends on the screen reader and how it's being used. Things like code tables are always bad to navigate. In this answer, however, I can choose to have the entire paragraph read all at once, like there's not code formatting there, or I can switch into "character" mode so it spells out what only the code span says, which allows me to hear the parens (having the code format means I don't have to read the entire paragraph char by char). It's hard to explain so tell me if you want to know more.
    – Laurel
    Commented Sep 22, 2022 at 12:03
  • @Laurel No, I don't need more information, thank you. What I meant to say is, that I don't think that there are really that many on Stack Overflow. Even when the reader can switch between modes, that only works well for clear separated blocks of text and code. Inline code would be bad again. So I don't think users who rely on such readers to access the content stay on this page that long. You (or anyone else) can still edit links to improve on that front, but I don't think that targeted audience for those edits is actually on this site (in considerable numbers).
    – Tom
    Commented Sep 22, 2022 at 12:32
  • 6
    @Tom it's a closed loop. If not many screen reader users visit, that would be because the site is not screen reader friendly. And you're saying that because not many visit, we should not have the site be screen reader friendly. If you have any objections that such edits cause harm, do voice them. Just trying to weakly object accommodating people with disabilities is not, in fact, a point worth considering against making these edits.
    – VLAZ
    Commented Sep 22, 2022 at 13:49
  • 1
    @VLAZ "And you're saying that because not many visit, we should not have the site be screen reader friendly" ... Please quote the line where I say that. I even say that users can still edit links and you write "If you have any objections that such edits cause harm". Do you twist my words on purpose?
    – Tom
    Commented Sep 22, 2022 at 16:36
  • 3
    @Tom you seemed to object to introducing more screen friendly links and said that not enough screen reader users visit. If that's not what you said, then I really don't get why you bring up "I don't think that targeted audience for those edits is actually on this site (in considerable numbers)" at all. Seems like a complete non-sequitur.
    – VLAZ
    Commented Sep 22, 2022 at 17:43
  • @VLAZ Because I think it could be time spent (when you edit posts for that sole reason) that doesn't has much impact, because the people who would gain the most from it aren't really here. People can still use their time how they want it's not my business, but this might not have much impact on how accessible the page is. But the issue, at least in my opinion, isn't a few formatting issues her or there, but the nature of the site. Posts regarding computer science/programming often come with different formattings, for certain highlights, code snippets, listings, tables etc.
    – Tom
    Commented Sep 22, 2022 at 22:39
  • 2
    @Tom accessibility tends to help all users. Not only the ones who have trouble in specific area. I don't think it's ever a wasted effort.
    – VLAZ
    Commented Sep 23, 2022 at 7:00
12

If this is the only change to the post, then it might be too minor. Maybe, depends on how long and/or readable the link is. And how many such links are replaced. If there are many links listed, then just plain having a shorter body of text might be an improvement.

But if it is part of other good improvements, I do not see a reason to reject the suggested edit over it.

Make a judgement call on whether or not inlining the link is an improvement or not. It is also fine to make no judgement and skip.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .