doc: many small fixes to deprecations.md by Trott · Pull Request #20519 · nodejs/node (original) (raw)

Make the deprecation message a bit clear and concise.

Make the text slightly more concise. Fix awkward verb tense.

Make deprecation text slightly more concise and direct.

Fix a typographical error in deprecation text. Convert run-on sentence to two sentences (one in parentheses).

Make deprecation text more concise and direct.

Change backwards compatibility to backward compatibility.

(It's confusing because "backwards compatible" is acceptable because "backwards" can be used as an adverb like that. However, as an adjective, as in "backward compatibility", only "backward" will do. Easiest solution: Always use "backward" because it is OK in both cases. This is all compounded by the US vs UK English thing. US English tends to favor "backward", and we standardize on US English, so that's another point in favor of "backward" over "backwards" in this context.)

Use "Node.js 6.0.0" instead of "Node.js v6.0.0". (We decided to drop "v" before version numbers to avoid confusion with the V8 JavaScript engine.)

• v10.0.0 -> Node.js 10.0.0
• Parenthetical with URL rather than "PR" as a lot of people may not know what "PR" stands for but they will know what a URL is. Plus not hiding the URL means the text is more copy/paste-able. In this particular case, "PR 12562" is not more useful or informative than nodejs#12562 so just use the URL.

• "un-deprecation" ಠ_ಠ -> "revoking deprecations"
• "From time-to-time" -> "Occastionally"
• "semver-major" and "semver-minor" are jargon that readers who don't follow our issue tracker will not know. Remove the sentence as it doesn't really impact end users. The deprecation is revoked when it is revoked. Rules around the releases where deprecations can be revoked may be added to the COLLABORATOR_GUIDE in the extensive section about deprecations there. If so, great, but let's still remove it here as having the information scattered in two places makes it likely that one will be edited to contradict the other and then it won't be clear which one is correct.
• Remove unneeded italics. The italicized sentence is not hugely critical information that we desperately want users to know. Most users won't care. They will only care about the deprecation message that they are looking up at that moment.