Docs: Consider using a URL shortener for links printed by code

[JoshuaKGoldberg]

Before You File a Documentation Request Please Confirm You Have Done The Following...

• I have looked for existing open or closed documentation requests that match my proposal.
• I have read the FAQ and my problem is not listed.

Suggested Changes

We occasionally need to print long links in code. For example, when using a deprecated property, we'll print something like:

The 'typeParameters' property is deprecated on CallExpression nodes. Use 'typeArguments' instead. See https://typescript-eslint.io/linting/troubleshooting#the-key-property-is-deprecated-on-type-nodes-use-key-instead-warnings.

That link is long and unwieldy. Also, if we ever want to change the page path and/or hash link, we need to set up redirects. I'm working on #8926 right now and can already tell it's going to be lot of netlify.toml entries - and maybe even runtime code.

Proposal: how about we start using a URL shortener for smaller, more permanent links? A few options come to mind:

• Same domain, verbose keys: https://typescript-eslint.io/link/key-is-deprecated
• Same domain, short keys: https://typescript-eslint.io/link/abc123
• Shorter domain, verbose keys: https://tseslint.io/key-is-deprecated
• Shorter domain, short keys: https://tseslint.io/abc123

tseslint.dev and tseslint.io are both available...

Affected URL(s)

n/a

💖

[bradzacher]

Sounds like we want to emit some error codes!

[rubiesonthesky]

I understand that they are long, but I like to see the title of the thing that is linked before opening that link. It also sometimes helps to find that page with search if you did not immediately open it from console.

For creating new domain, not sure if that is always desirable because it’s better to trust and open link that you know will go to right site.

So even if the link is really long, it may be more user friendly than shortened link. (Unless for example you have those error codes and then link would use that code)

my preference from these would probably be the first but maybe say “error”.
https://typescript-eslint.io/error/key-is-deprecated

[bradzacher]

The big win of a shortened URL that redirects is that we can update the redirect when we change the docs. This means that old versions can still get relevant docs instead of broken ones.

It also sometimes helps to find that page with search if you did not immediately open it from console.

I'm not sure what you mean - are you saying you would manually open the docs and then manually navigate to the relevant page and manually find the correct header instead of just copy+pasting the URL? That seems like a good way to get lost!!