Should we hide aliases for renamed resources?

[joeduffy]

We have a number of resources that have been renamed over time, whether to fix spelling mistakes (e.g., Webook versus Webhook) or reclassification of modules (e.g., moving resources from role to authorization). This don't show up distinctly in the docs so when someone is writing new code, it may not be clear which one they are supposed to use. Should we just hide the old/deprecated names or at least add a warning that redirects them to the preferred name?

[joeduffy]

Oh, I see we do have a message for the resources:

A few thoughts:

1. It's a bit buried (below the examples), why not put this right at the top?
2. Can it be hyperlinked?
3. Should we tell you about entire modules (like role) that are entirely deprecated too?

I spent a good 20 minutes spelunking around in the docs before I realized the resources had moved, and didn't even see the error message until after filing this issue!

[cnunciato]

It looks like we've moved these to the top of the page, which is good -- although it looks like the formatting is failing in at least some cases, so I've filed https://github.com/pulumi/docs/issues/9541 as a follow-up.

Also filed https://github.com/pulumi/docs/issues/9542 to cover linking to replacement resources, as that seems like something we should do if we can.

As for hiding aliased resources, I think given the deprecation notices are more visible now, it'd probably be better to keep these resources around than exclude them. Looking at the schema, it looks like we can tell (a) that a resource is aliased and (b) that it's deprecated, but I don't think that's quite enough info to be sure the resource is "bad" and should be hidden from users.

So I'll close this for now, but feel free to reopen if you feel like there's more to work out and we'll do so!