"Use instead" or "superseded by" for deprecated features

[harry-wg]

When a feature is marked as deprecated, it would greatly help if mdn could include recommendations of better features that replace it.

Part of the problem is that deprecated features will nevertheless come up as the first results in search engines. So, simply marking a feature as deprecated (or obsolete) is no help to man or beast if there is no link to a suggested replacement.

[teoli2003]

Yes! I try to do this. But it is not always easy to find, and sometimes there is no replacement (e.g. Document.execCommand for non-clipboard commands)!

I would answer that we will accept any PR, or deal with any issue, that solves this concretely: that is any issue that suggest the missing information (the replacement) will be dealt with.

[harry-wg]

sometimes there is no replacement

Then it would be useful to say that there is currently nothing else that is similar, to avoid everybody wasting their time fruitlessly searching for one.

But I would argue that until there is a replacement, it's maybe premature to mark the feature as deprecated -- unless the feature is actually unsafe to use in the meantime.

[hamishwillee]

Then it would be useful to say that there is currently nothing else that is similar, to avoid everybody wasting their time fruitlessly searching for one.

I agree with this.

I think a big part of the problem is that we have four formal ways to mark deprecation (inline and header macros, bcd, tags) but no standard way to mark "superseded by". If there was a formal way/hint to indicate a replacement I think that authors might at least think about this.

it's maybe premature to mark the feature as deprecated -- unless the feature is actually unsafe to use in the meantime.

Not so sure on this. There are many cases where features are deprecated with no replacement. Probably the problem is that no one uses deprecated consistently. MDN often means "discouraged", which could be for lots of reasons, including that it doesn't have broad support.