Docs: Relabel Automatic Redirects as "Incoming links: Best practices and redirects" (Diátaxis) #9896
Conversation
benjaoming
requested review from
ericholscher
and removed request for
a team,
humitos and
agjohnson
benjaoming
changed the title
docs/user/automatic-redirects.rst
Outdated
| .. seealso:: | ||
|
|
||
| :doc:`/versions` | ||
| Read more about how to handle versioned documentation and URL structures. | ||
|
|
||
| :doc:`/user-defined-redirects` | ||
| If you delete or move a page, | ||
| you can setup a redirect in place of the old location and choose where users should be redirected. |
docs/user/automatic-redirects.rst
Outdated
|
|
||
| * Use ``/page/path/to/page.html`` if you are linking to the page in the default version of the default language. | ||
| * Use ``/en/latest/path/to/page.html`` if you want to be specific about the language. | ||
| * If you move a page that likely has incoming references, :doc:`create a redirect rule </user-defined-redirects>`. |
There was a problem hiding this comment.
| * If you move a page that likely has incoming references, :doc:`create a redirect rule </user-defined-redirects>`. | |
| * If you move a page, :doc:`create a redirect rule </user-defined-redirects>`. |
Always create a redirect. It's hard to know if there is incoming references to a page.
There was a problem hiding this comment.
Maybe we should suggest to use Traffic Analytics to be informed before making decisions to (re)move content.
There was a problem hiding this comment.
I think we shouldn't write this "bombastically" - it should be possible to move a page without worrying too much. Later we make the point about 404s being useful.
There was a problem hiding this comment.
If we are adding a section about "Good recommendations", I'd say we should recommend to always create a redirect if you change a URL. No matter if there were too many pageviews in the last month(s) or not. You never know where your URL is linked from 😄
There was a problem hiding this comment.
Manuel did a great copy edit here, and I agree with most of the feedback. I'd also give some feedback at a high level which seems like this page is trying to mix reference & explanation and it doesn't work well. The section on permalinks feels really odd and different in tone than the rest of the article.
I think we should probably consider moving this back to a feature reference and an explanation. I also wouldn't frame the explanation as a question, since we don't do that anywhere else? Similarly, the best practices & "what not to do" seem odd for a explanation, at least as currently written -- though I'm not 100% sure where they belong. I can definitely see something like that being good explanation content though (eg. The value of permalinks)
Co-authored-by: Manuel Kaufmann <[email protected]>
…jaoming/readthedocs.org into diataxis/relabel-automatic-redirects
benjaoming
changed the title
After your comment, I changed a lot here, both the title and structure and intro. I think the "reference" part of the article is really minimal, especially after we removed some incorrect old legacy section. The remaining reference isn't really a type of reference I'd expect anyone to visit a documentation page to look for. So ultimately, I think that the entire content is better shipped as an explanation with focus on how to handle external links. Through my own "fresh eyes" reading, I think this goal is near after the latest changes 👍 |
|
I will give it a read over tomorrow. I ran out of energy today 😴 |
|
Talked about this on our call today. I think we have good next steps:
|
…g into diataxis/relabel-automatic-redirects
|
Just noticed that we have this page: https://docs.readthedocs.io/en/stable/guides/deprecating-content.html |
…bit further.. but not quite there yet
…jaoming/readthedocs.org into diataxis/relabel-automatic-redirects
…g into diataxis/relabel-automatic-redirects
|
@ericholscher what you mentioned in #9896 (comment) from our earlier call this week is implemented here and ready for review 👍 |
|
@ericholscher PR is ready for another review 👀 |
After reading this, I decided to expand the scope to deal more generally with the question of how to handle incoming links.
I think this would be the main theme that the reader is tackling when reading the explanation.
I added a lot of cross-references already. Potentially, more could be added.. but I got a feeling that the page would drown in cross-references at some point.
Other than that, I think this looks like a fine improvement. All the contents were already "explanation" so pretty easy to move.
Refs: #9746
📚 Documentation previews 📚
docs): https://docs--9896.org.readthedocs.build/en/9896/dev): https://dev--9896.org.readthedocs.build/en/9896/