26

I am answering some of SE questions by linking my own code examples from Documentation topics.

e.g. Difference between Strategy pattern and Command pattern

In future, is there any possibility of someone else removing my documentation content? If that is the case, my documentation links will be broken in SE answers.

In that case, I would like to keep code example in my answer itself.

8
  • 1
    Hmm yeah, that's a very good observation. Given the nature of Documentation (massive collaborative editing), it is very possible that the specific example you refer to will be massively rewritten or even removed entirely at some point in the future. That would make your answer confusing and less helpful. I don't really have a good answer for this, other than to say that all answers should be self-contained. If there's code that is relevant, include it directly in the answer. Best keep Documentation and Q&A separate.
    – Cody Gray Mod
    Commented Aug 23, 2016 at 10:23
  • 10
    Documentation is supposed to be set up so that the link doesn't go dead. (I haven't tested this claim.) How it's supposed to work is the link you post in your answer is supposed to be tied to a specific point in time for that topic/example. This way, if someone updates it for a new version, the version of the documentation in your answer should remain linked as it was.
    – Kendra
    Commented Aug 23, 2016 at 13:03
  • Understood. But there is an option to delete entire topic I think. Commented Aug 23, 2016 at 13:53
  • 4
    I no longer trust any promises of Stack Overflow keeping any of its links alive since it started mass culling content around 2010-11. It's likely that intra-Documentation links will be updated accordingly, though.
    – Pekka
    Commented Aug 23, 2016 at 13:56
  • @Pekka웃 is my very biased point of view that quite the contrary has happened, SO seems strongly against any content curation that implies deletion.
    – Braiam
    Commented Aug 23, 2016 at 14:44
  • 2
    @Braiam loads and loads of old off-topic questions were deleted in those years, with loads of inbound links.
    – Pekka
    Commented Aug 23, 2016 at 14:46
  • 3
    @Pekka웃 yet I've never hit any of those links. Which is why my point of view is very biased.
    – Braiam
    Commented Aug 23, 2016 at 14:47
  • 1
    As you've done in the linked answer, the best thing to do is to provide links to supplementary information, rather than information that the answer depends on. As long as people do that for all links, whether to Documentation or elsewhere, there shouldn't be any issue. Commented Aug 23, 2016 at 18:02

2 Answers 2

27

Links to Documentation include a timestamp to make the exact version you link to viewable for all time.

By default the latest version is shown (future revisions are hopefully improved, after all), but a banner linking to the older version is added.

Old version option

If an example is deleted (but the topic still exists), you'll see an option to view the topic as it was before the example was deleted.

Option to view before example was deleted

If the entire topic was deleted, you'll get one of two options depending on whether your link includes a stamp (and if the timestamp points to a date prior to deletion).

Whole topic deleted

The only exception to being able to view deleted content is if the content had to be taken down permanently for some legal or moderation reason: things like social security numbers, bank account info, DMCA requests, pornography, spam, etc.

8
  • 35
    If someone has used a link with a timestamp, then that means the person who created the link wanted the version matching that timestamp, not the current version. If the link that is being followed includes a timestamp, then the proper action by the system is to show the version with that timestamp. A banner can be added saying that it is an old version and "click on this link to see the current one". It is not appropriate for the default to be to show the current version with a banner showing a link to the version matching the timestamp.
    – Makyen Mod
    Commented Aug 23, 2016 at 22:06
  • 1
    Does this mean that if I'm linking to docs, I should use the UI to insert the link rather than copy/paste the URL? Or will pasting in a non-timestamped URL get converted automagically for me?
    – DavidG
    Commented Aug 25, 2016 at 8:30
  • @Makyen Would you not want the most polished version with all of the mistakes corrected and caveats added? If you follow a link to a Q&A question you want it to have all the useful edits and comments added since the link was copied.
    – rdans
    Commented Aug 25, 2016 at 8:59
  • 1
    @rdans See the question here. Mistakes can be corrected but in Docs also content can be changed and not be present anymore. It's probably better to show the exact content that the answerer had it mind when writing the answer because that comes closest to the original intent. Q&A mostly only improves when getting an edit, but Documentation is expected to change more with each edit. Commented Aug 25, 2016 at 9:04
  • @rdans, To show the current version, or a specific version, is a choice I make when adding the link to a document. If I want the most recent version, then I add a link without a timestamp. If I want a specific version, then I add a link with a timestamp. Simple. If the link has a timestamp, then the page at the time indicated by the timestamp is what the author of the content containing the link intended to be viewed. Having the system usurp that author's intent to show the current version is just wrong. Doing so violates the entire reason for having a timestamp in the link.
    – Makyen Mod
    Commented Aug 25, 2016 at 10:05
  • Its not necessarily a conscious choice though. The time stamp is automatically in the URL so a general user finding the documentation who isn't paying close attention to the format of the "t" parameter in the URL will not know that their link includes a time stamp and that they need to remove it if they want to link to the latest version
    – rdans
    Commented Aug 25, 2016 at 10:16
  • @rdans, Then that is a bad UI/site design choice, which needs to be corrected. If the system can handle both having a timestamp in the link, and a link without the timestamp, then when normally navigating and when being offered a link to share, the user should be using/provided with the non timestamped version of the URL. The timestamp should only be used in the URL when the user selects a less visible option to "share this version of the page", or when needed by the system (e.g. to show an old version to verify that the user wants to revert to that version).
    – Makyen Mod
    Commented Aug 25, 2016 at 10:29
  • @Makyen The URL states "This is a link to this documentation topic created at timestamp X". You might want it to read "This is a link to the documentation topic at timestamp X", but that is not what it means. The timestamp simply exists to permit the person following it to time travel if something went wrong, it is not intended to permit deep-linking to a past version. I claim both may be useful, but a deep-link to a specific version is less useful to the general user assuming SO documentation is healthy. If you want your version, make a feature request, but don't break existing one. Commented Aug 25, 2016 at 20:16
4

Tim Post mentions in Link-only answers targetting SO documentation?:

In essence, while links to docs are probably 'safer' than others, we should treat it as a supplementary resource and still take a moment to write an extra sentence or two that points out what the reader should be looking to take away from the resource.

Supplementary resource means you have to copy the relevant sections anyway and linking is not enough.

Kevin Montrose explains in his answer that the links have a timestamp and that the version corresponding to the timestamp can be shown (although only after one additional click).

This means the Documentation links do not become broken but a bit hidden. If you don't like this, link to a specific version directly (should be possible, haven't tried it myself).

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