-2

Documentation on how to write a good answer states:

Provide context for links

Links to external resources are encouraged, but please add context around the link so your fellow users will have some idea what it is and why it’s there. Always quote the most relevant part of an important link, in case the external resource is unreachable or goes permanently offline. Links to other websites should always be helpful, but avoid making it necessary to click on them as much as possible.

I was wondering how we could also encourage both askers and answerers to provide a permanent version of their link when it exists.

For instance, I believe it's quite common to link to a project's source code pointing to a specific line of a file. However, when you browse a git repository, you will see the code as the current position of the main branch. The link will thus quickly be outdated and point to the wrong line. That's a shame since there is an easy way to overcome this issue by replacing the branch's name by the sha of the latest commit (or a tag).

On the other hand, links to a project's documentation often point to a specific release, while providing a permanent URL to the latest stable release could be used to avoid misleading future readers with an outdated documentation (if still available at all). Being able to compare the current version of the documentation with the excerpt quoted in the SO post, could also hint the reader about changes that deprecate the answer.


As an example, in this question:

I referenced Django Query docs: https://docs.djangoproject.com/en/1.4/ref/models/querysets/ And unit tests for samples: https://github.com/django/django/blob/master/tests/modeltests/or_lookups/tests.py

The links would still be valid today if they were written so:

I referenced Django Query docs: https://docs.djangoproject.com/en/stable/ref/models/querysets/ And unit tests for samples: https://github.com/django/django/blob/1.4/tests/modeltests/or_lookups/tests.py

Although the strict necessity of these links to answer this specific question is arguable, it is generally appreciated to show that you have made some research before asking and share the state of your research.


In this other example, the answer author referred to the source code to explain his solution:

You can do the following:

from django.core.exceptions import SuspiciousOperation
raise SuspiciousOperation("Invalid request; see documentation for correct paramaters")

SuspiciousOperation is mapped to a 400 response around line 207 of https://github.com/django/django/blob/master/django/core/handlers/base.py

This reference was not strictly required to answer the question, but it is still valuable. It demonstrates how they found the solution, allowing the readers to dig further if they want. This is also a good way to spot a possible deprecation of the post. Which is exactly what someone mentioned in the comments: "Neither SuspiciousOperation nor 400 are in the code you linked to. I guess it's changed."

Had they written this link as https://github.com/django/django/blob/1.8/django/core/handlers/base.py#L195-L205 we could at least see what he was referring to, the context around, and figure out how it has changed to adapt the answer to newer versions.


In another answer to the same question, someone referenced their statement with the documentation:

see the doc on exceptions.

The link is useful to show where the information can be found and allows readers to find specific information to their use case. However:

  1. The link points to the french version of the documentation
  2. The link points to a specific version of the documentation that will one day return a 404, while it should be valid for any version starting from 3.2.

In such case, linking to https://docs.djangoproject.com/en/stable/ref/exceptions/ would be much more relevant than https://docs.djangoproject.com/fr/3.2/ref/exceptions/


Could we do anything to encourage users to be aware of theses issues and how to overcome them?

Just to be clear, this is an open question. Although I gave my opinion on "good links" along with examples, this is only intended to illustrate some issues with links and possible solutions. Whether it is better to link to a fixed or floating version depends on the case, the likeliness that the link will become outdated, how quickly, ...

The scope of this post is to try to find general guidelines that could help writing better links and share them to help authors, editors and reviewers to improve the quality of posts.

14
  • 11
    Regarding documentation links, I would argue against using "stable" (or "current" or whatever) in the links. You're correct that someone might be confused when documentation links to an older version, but they would be equally confused when the answer post and the documentation contradict each other, because the answer itself is outdated. It is better to link to the explicit version the answer relies on and then "mark" the whole answer as outdated. I guess that's what the "Outdated Answers project" wants to fix
    – Tom
    Nov 18, 2022 at 13:46
  • Agreed. That's why I added "Being able to compare the current version of the documentation with the excerpt quoted in the SO post, could also hint the reader about changes that deprecate the answer.", but that's indeed arguable. I'd say linking to a specific version or the latest version should be decided on a per-case basis. Nov 18, 2022 at 13:49
  • 4
    The "How do I write a good answer?" and "How do I ask a good question?" in the help center mention a few things about links, but they could be improved at least encourage users to be aware of these issues, if not more. Nov 18, 2022 at 14:01
  • 2
    "For instance, I believe it's quite common to link to a project's source code pointing to a specific line of a file." even if it is, it should not be. That's one of the quintessential examples of exceptionally bad links and the reason we want self-sufficient posts. Rather than encouraging "permanent links" like these, we should be very heavily discouraging these links. Posts shouldn't at all rely on those. Even if it's "static", if a future visitor cannot access it because of a firewall or whatever, then the post becomes useless.
    – VLAZ
    Nov 18, 2022 at 14:33
  • 1
    "As an example, in this question: [...] The links would still point to the right line today, if it were written so" and? I've read the question but I fail to see why you'd actually want to visit the links in the first place. I don't know Python, and I didn't check even the updated links but to me it doesn't seem it would help at all. All the solutions just deal with user code, not with the library code. I'm not seeing the value of having links to the library code. Even if they are "fixed", so they point to the correct line.
    – VLAZ
    Nov 18, 2022 at 14:41
  • 4
    There are very few cases on Stack Overflow that need to link to it in a preserving manner. The majority of the time, the links are redundant. We need to encourage people to use fewer links to avoid these problems, and as the help center already covers, ensure the on-site answer isn't dependent on the link to remain valid.
    – Zoe is on strike Mod
    Nov 18, 2022 at 14:44
  • 2
    @VLAZ In the Python tag I've often seen linking to source code as useful for content relating to libraries with underspecified interfaces/guarantees. "LibFoo does bar without spawning nasal daemons" is a statement useful by itself, but additionally linking to either official spec or just source code can make clear (and allow checking) how strong the guarantees are. Think of it like citing a reference for a statement – it's useful extra information if available but the statement still works by itself. Nov 18, 2022 at 15:03
  • 2
    Provided links should be redundant and the relevant excerpt should be quoted in the question. I have nothing to argue about that. However, I don't believe links should be discouraged at all. They provide valuable context to dig deeper in the question or the answer, while pasting the whole context would flood the key part in too much noise. It also provides meta information that could indicate that the post is mistakenly referring to the wrong part of the code. And it shows how you found the answer, sourcing your statement and helping the asker to understand how to find it by himself next time. Nov 18, 2022 at 15:38
  • 2
    @AntoinePinsard very valid points. I wish they were part of the meta post rather than a long comment train :) Meta dwellers need help to not have knee-jerk reactions to topics which come up ad nauseam and the topic of links is surely one of them.
    – Gimby
    Nov 21, 2022 at 15:53
  • @Gimby Thanks. This is would unfortunatly be off-topic. My intention was to raise attention about how to write better links and encourage it, not debate whether links are useful or not. The question is quite open, I don't believe there is anything to be pro or con in my question. Nov 21, 2022 at 18:08
  • 1
    I updated my question to clarify the subject and give more concrete examples. Nov 21, 2022 at 19:44
  • 1
    Sure, there's loads of different ways to poke and prod authors/editors into providing more permanent links. Can we prove to SE that any of them would be worth spending dev time on? Is this a rampant problem?
    – Kevin B
    Nov 21, 2022 at 19:47
  • some slightly related discussion I solicited from some CMake folks via chat on how they choose whether to link to a pinned doc page version, or to a rolling latest doc page. Link here is to a response by one of the CMake maintainers.
    – user
    Nov 22, 2022 at 9:44
  • 2
    Antoine, I think you'll hep prevent confusion about the focus of your post and better frame the post body by making your post title more descriptive of what you want the discussion be about: which my understanding is (not sure if correct): "whether and how to give guidance to users to help avoid pitfalls".
    – user
    Nov 22, 2022 at 9:47

1 Answer 1

4

I was wondering how we could also encourage both askers and answerers to provide a permanent version of their link when it exists.

I don't think that is feasible, for the simple reason that it has to solve directly opposite goals:

  • In your code example, "permanent" means a specific version.
  • In your docs example, "permanent" means a current version.

And that is not even a clear relation of use-case to kind. One might well want to link to a current version of code to stay future proof or link to a specific version of docs to avoid the page going away.

As two examples of your own domain, Python, for "how does dict work" one would link to a current code version to reflect changing reality whereas for "what are the collections ABC" one would link to a specific docs version version because the thing has changed both meaning and location.

Notably, which one is which is known only after the fact: Generally, you just do not know whether a "specific" or "current" link is better. Instead, you only find out over time when the link stays relevant or becomes outdated.

Ultimately, the only authority on "how to link to resource X" are the maintainers of said resource. Whether they provide such advice or not, Stack Overflow trying to give additional advice on how to guess what to do is likely to lead to more confusion than clarity.

You must log in to answer this question.

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