search

aiven / devportal

Resources for users of the projects on the Aiven platform
https://docs.aiven.io
Creative Commons Attribution 4.0 International
60 stars 53 forks source link

Replace redirected links #1485

Closed laysauchoa closed 1 year ago

laysauchoa commented 2 years ago

We have more than 120 redirected links in the docs. It is better to make clear for the user what they are accessing, and even to ourselves where those redirected are taking us to visit as we have in our docs. You can find the redirects by running linkcheck.

laysauchoa commented 2 years ago

From your experience with documentation @TibsAtWork does this make sense? Any feedback is helpful, thank you

TibsAtWork commented 2 years ago

I don't have any directly useful experience, but some thought

My worry about putting comments into the text (which I've done myself on occasion 😢) is that it doesn't get updated - and in the worst case, the target may change so the link is no longer a redirect and then the comment in the text is just wrong!

However, there are some simple things we can do to reduce the number of redirects we're seeing, which we should probably do first.

I (just now) see 129 redirected links (searching for redirect in the logs)

That's 145 where we either have something to fix, or are definitely already doing the right thing. And yes, that's more than 129, so some things are occurring more than once, which is OK, but it does suggest we might reduce the (apparent) problem rather dramatically with some relatively simple changes.

TibsAtWork commented 2 years ago

It occurs to me that I didn't make it obvious how pleased I am that you're looking at this! It's definitely something we should be keeping track of, so thanks for doing so.

laysauchoa commented 2 years ago

Thanks for the nice summary @TibsAtWork I've noticed that some were related to the http and https. But having them in such a summary is very helpful to understand the issue better.

My initial idea was to replace the directed links in an automated way because we have a nice summary from linkcheck which we can extract the information about the redirects and use for the replacement. We can run a script that can replace the redirects in the rst files periodically for maintenance reason and open a pull requests with the changes, so we can review them.

This can guarantee continue review of redirects with proper human review before merging! ⚙️ What do you think?

TibsAtWork commented 2 years ago

I think I'd be tempted to sort out the easy-to-sort links by hand first - certainly the http and developer.aiven.io ones.

I'm assuming one always wants to ignore temporary redirects, but that is an assumption.

For the permanent redirects, I don't know if one can automatically tell which ones we want to change and which we don't. Again, I'd be tempted to do a pass by hand to fix those that are clearly "heh, you're using an out-of-date link", and then review again.

In the end, I think we should probably raise an issue to fix the http and developer.aiven.io links (they definitely need fixing), and maybe another to fix the permanent redirects that are wrong, and then review this issue again afterwards.

I can have a go at creating those issues and hopefully doing the work next week if you think it sounds sensible.

TibsAtWork commented 1 year ago

See the following PRs for work done so far:

laysauchoa commented 1 year ago

Thanks @TibsAtWork this solves the current re-directs. Feel free to check this other ticket to discuss redirects visibility.