-
Notifications
You must be signed in to change notification settings - Fork 961
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document in contributing guide what the process is for removing docs #1401
Comments
@pradyunsg made a valid point on #1345: if we redirect to an external domain, Sphinx's linkcheck will not check the redirect link, at least until documatt/sphinx-reredirects#6 is merged, whereas it will check it if we make an orphan page. So, I think it is reasonable to ask for orphan pages in that case. On the other hand, for an internal redirect, this is not a concern. We know that we don't break links ourselves. |
So... The obvious question here is what options do we have and what behaviours do the various options bring? I'm on a bus ride to get my glasses fixed, so let's see how much I can figure out on this ride.
And, even though the bus had to wait due to a protest calling for a ceasefire in Gaza, I didn't manage to finish this on the bus ride. And, yes, my glasses as fixed. |
Having done this review, I think the option I prefer out of all of these is using Read the Docs' redirects. They are the only option that preserves fragments and transparently forwards readers with an HTTP-level redirect. I guess past me did something similar along these lines, because I remember now that I wanted to move pip's documentation over to using these redirects that are in that YAML file in the root of that repo. Sorry folks for derping and originally proposing the orphan files approach here. 😅 |
I think I prefer orphan documents. We add a prominent header at the top of the document stating that the document is outdated (and maybe also the reason why) and of course a link to a better resource (or multiple links). Otherwise we do not change (or very minimal change) the content of the document itself. I would also be fine with removing the content and leaving only the deprecation notice. I do not really like redirects on the web. |
I've been reading about how HTML (meta refresh) redirects, as made by sphinx-reredirects, affect SEO. Although there is mixed advice in the wild, the overall theme seems to be "it's probably okay-ish but not recommended, use HTTP redirects instead". |
In general, I think the most important thing is to structure and name things so that readers can get the relevant packaging info they need. And you've all been doing an excellent job, it's great to see the improvements in recent weeks! 👍 Second, anyone making a website should put effort into avoiding linkrot when possible. It can be surprising how long links can live on elsewhere, and preserving links is part of serving our readers. |
#1434 highlights an aspect of the problem which has not been mentioned so far, namely how our restructurings affect projects linking to us with Intersphinx. Specifically, we can always keep labels so that Here is how each of the options behaves:
Do we want to reconsider orphan documents in light of this? (My opinion is that the advantages of HTTP redirects are still attractive.) |
There seems to be some confusion about whether it is best to remove a doc completely or to make it an orphan doc. This is related to redirects. It's beyond my expertise or historical knowledge of the project so will defer to opinions of others.
Once we have consensus or a decision, let's document it. Thanks.
See #1377, #1397
The text was updated successfully, but these errors were encountered: