doc: reorder deprecated tls docs - #34687
Conversation
Sorry, something went wrong.
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
jasnell
left a comment
There was a problem hiding this comment.
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.
Sorry, something went wrong.
jasnell
left a comment
There was a problem hiding this comment.
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.
Sorry, something went wrong.
Why do we want to do that? |
Sorry, something went wrong.
Frankly, to make deprecation easier to find, or easier to ignore. |
Sorry, something went wrong.
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 |
Sorry, something went wrong.
Doubt I'll have much luck winning folks over to my side ;-) ....won't block
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 PR-URL: #34687 Reviewed-By: Rich Trott <rtrott@gmail.com>
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 PR-URL: #34687 Reviewed-By: Rich Trott <rtrott@gmail.com>
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 PR-URL: #34687 Reviewed-By: Rich Trott <rtrott@gmail.com>
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 PR-URL: #34687 Reviewed-By: Rich Trott <rtrott@gmail.com>
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 PR-URL: #34687 Reviewed-By: Rich Trott <rtrott@gmail.com>
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