doc: reorder deprecated tls docs

[jeromecovington]

In other api docs, it seems that deprecated classes and methods are
listed along with others, and marked as deprecated. In tls docs,
deprecations were listed at the bottom of the document. This commit
reorders them to what seems to be the standard, and corrects some links
in doc/api/deprecations.md

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[jeromecovington]

cc @Trott

[jasnell]

This had been done intentionally to try to encourage that pattern throughout the other docs. I'd much rather see us go the other direction, moving deprecated APIs out to separate sections.

Hit the wrong button

[jasnell]

This had been done intentionally to try to encourage that pattern throughout the other docs. I'd much rather see us go the other direction, moving deprecated APIs out to separate sections.

[Trott]

This had been done intentionally to try to encourage that pattern throughout the other docs. I'd much rather see us go the other direction, moving deprecated APIs out to separate sections.

Why do we want to do that?

[jasnell]

Why do we want to do that?

Frankly, to make deprecation easier to find, or easier to ignore.

[Trott]

Why do we want to do that?

Frankly, to make deprecation easier to find, or easier to ignore.

Easier to find: I don't think we should optimize for "I need to find all the deprecated functions in one place". I think we should optimize for "I need to know how this function works. I need to find it in a predictable place in the docs. I don't know that it's deprecated, or wouldn't think to look Someplace Else for deprecated functions."

Easier to ignore: Valid, but similarly, I don't think it's what we should optimize for over "the method is where I expect to find it".

The tls doc does not have all of the deprecated APIs listed in that section. So it's already arguably kind of a failing experiment. server.connections is not there. And moving it will change any the links to it in our docs or on the internet, increasing friction for deprecation changes. Breaking working URLs is also a big negative to the approach. (EDIT: Crossed out because actually, that depends on how it's done, so arguably not a valid concern on my part.)

On balance, I support this change and halting any move to requiring deprecated APIs to be tucked away at the bottom of the docs.

/ping @nodejs/documentation

Doubt I'll have much luck winning folks over to my side ;-) ....won't block

[Trott]

Landed in be360e2