If this word continues to appear in this file, it should have a content warning at the top, and/or a content warning and a click-through to view this section.

I'm fine with a content warning within this line item (where it's more likely to be seen when someone clicks through to find the information for the specific deprecation code. However, it would be helpful if you had a specific suggestion for the wording of such a warning.

Would it be possible to not include worker.suicide inside the error message but rather a reference to the documentation?

### DEP0007:  The api used is deprecated, please replace with worker.exitedAfterDisconnect. Please refer to documentation for more information.

In the extended documentation we could start with

Content warning: Self Harm.

Please click here to skip to the next entry.

We can then make "click here" an href to the next header

the name of the property is not included in the warning message that is printed to the console., it is included only in this one deprecations.md document. I'd rather not make it any more complicated than that.

This would be an improvement:

 <a id="DEP0007"></a>
 **Content Warning**: self harm.  [Click here to skip to the next entry.](#DEP00008)

-----

### DEP0007: Replace cluster worker.suicide with worker.exitedAfterDisconnect

A much better approach would add a CSS rule like this:

#DEP0007Content { visibility: hidden }
#DEP0007Content:target { visibility: visible }

and then

 <a id="DEP0007"></a>
 **Content Warning**: self harm.  [Click to show](#DEP0007Content)

<div id="DEP0007Content">
...

I realize this adds some complexity, but it's not like it's something we'll have to do very often, and it seems like a very reasonable cost for the benefit it provides.

Shoot. I just now saw this comment come through @isaacs .... of course it was immediately after landing. This specific additional change can be handled and discussed via a separate PR. Sorry about missing it.

@jasnell No problem. Improvements can come iteratively :) Do you want me to take a crack at writing that update, or do you want to tackle it?

I disagree with giving sentimental assessment ("unfortunate") to the naming of the property here. It should be a purely technical explanation of the change.

For that, I disagree. One thing we've have consistently needed to get better at is explaining why things are deprecated and removed.

I think you misunderstood. I'm not arguing against explaining why. My gripe is with the word "unfortunate" and the apologetic tone.

Regardless of how one feels about "unfortunate", I do think this text:

The naming of the property is unfortunate not only because it is not entirely accurate of the exit semantics, but also because of the potential emotional impact the word carries. In Node.js 6.0.0, the old property was deprecated and replaced with a new [worker.exitedAfterDisconnect][] property.

...would be better as:

In Node.js 6.0.0, the old property was deprecated and replaced with a new [worker.exitedAfterDisconnect][] property. The old property name was inaccurate and unnecessarily emotion-laden.

(If nothing else, please clean up the awkward "accurate of the exit semantics" phrase.)

I just updated the text but I like your suggestion here better @Trott

Updated to use the suggested wording

Minor nit: I don't think a property name can be "inaccurate", how about "misleading"?

I think inaccurate is preferable to misleading here.

"The name is inaccurate" doesn't seem to be...uh...inaccurate. :-D

"The name is misleading" seems a bit loaded and I think less accurate.

Other options, although I'm fine with inaccurate: imprecise, confusing, difficult to construe, easy to misunderstand

Yeah, I'm not sure that misleading is any better. imprecise could work.

My point is that the name of a property doesn't need to be 100% descriptive, it's usually kind of a mnemonic. In a sense, all property names are "imprecise" to some extent. In case of the property in question, the meaning of the word is quite different from the purpose of the property, which makes it easy to misinterpret/misremember.

inappropriate? Not appropriate for node in general & not an appropriate description of the status.
Or simply not good

incomplete? inadequate?

We could also just remove the inaccurate part entirely as it's not the primary reason for removal AFAICT.

If we want to get better at explaining why we removed something, as @jasnell implores us to do, being direct is probably best anyway:

The old property name was unnecessarily emotion-laden.

Rather unfortunate terminology here, in context. I don't have a better suggestion though :\

We could replace all instances of End-of-Life with Broken and/or Removed, that might be more accurate terminology anyway (but we can also keep that for a follow-up, that might be easier).

This is a fixed term as defined in deprecations.md, so I don't think we want to change this.

I noted the irony also. To change this we would need a change to the deprecation policy as a whole, and the usage here is consistent with general usage in the industry. That's not to say it's particularly good, just that for now there isn't a better option.

@tniessen I know, as I said I’m suggesting that we change the terminology, not this single instance.

@addaleax We both wrote our comments within a minute, I did not see your comment until I had written mine, I was not responding to you ;)