Define recommendation format

[celestehorgan]

Define a format for all recommendations.

Currently we're using the format proposed by the Kubernetes Working Group naming, but this doesn't have to be what this group ends up with.

I suggest the following at a minimum:

• [ ] Word/phrases to replace
• [ ] Preferred replacement(s), with notes specific to different verticals as required
• [ ] Reasoning and justification for making this change (to generate buy-in)
• [ ] Citation(s) of other work on the web (existing work within SDOs, i.e.)
• [ ] Severity (i.e. "Replace immediately", "consider replacing")

Existing: https://inclusivenaming.org/language/word-list/

[richsalz]

Seems pretty complete to me.

[celestehorgan]

Karsten, Meg, Monica, Joanna, Julian

[quaid]

I'm in for this @quaid

Just coming out of the meeting thought: It could be good to find a way to tie "Severity" back to the orders of concerns in the Eval Framework. E.g. something that is entirely third-order concern is likely to have a lower severity.

Is it worth having a stand-alone section or specific call out that focuses on the elements of making a good decision (a conscious choice) about the word/term?

[julian-cable]

I suggest to add a Status field. At IBM, each term in our Word usage list is assigned to one of the following categories (listed in ascending severity order):

• Preferred: The approved term to use.
• Use with caution: Use the term only in a specified context; otherwise use a stated alternative.
• Do not use: Never use the term; instead use a stated alternative.

I think that adopting a similar categorization for this initiative would be useful to cover a nuanced approach that will be needed in defining some of the terms.

[celestehorgan]

@julian-cable Is there a public example of IBM's word list format that we can see for reference?

[julian-cable]

@celestehorgan I have prepared a suggested example and have asked Carla to run it by IBM Legal for sharing externally.

[mheis63]

@celestehorgan adding a comment so my github username is here as well

[markcmiller86]

Regarding status of a term (or its proposed replacements), is there any way we can capture actual metrics (maybe from a sample corpus) that would indicate each term's frequency of use, how widespread or how much that term may have been now replaced by its alternatives? Thats potentially a longer term consideration but migth be useful in supporting the proposed changes and in convincing slower moving members of the community to update faster.

[markcmiller86]

On the word Severity, the explanations I am reading here about what that means sounds more like urgency? And, though I don't see it explicitly mentioned here I wonder if this aspect of a term relates somehow to degree or extent of harm the term causes to others? That would certainly be difficult (and maybe not even productive) to metricize and maybe the rationale supporting any specific flagged term will suffice but I wanted to at lest raise the question about what whether Severity is aimed at capturing this aspect of things?

[mheis63]

As @markcmiller86 said, I don't think Severity is an accurate term for the "definition" given. I read this more as Priority , much like a software bug where a higher Priority would indicate it needs to be addressed sooner. But Priority also introduces a biased aspect to the term, though whether or not we are the decision makers on what is high vs low priority, I think that is beyond the scope of this issue

[richsalz]

Importance?

[markcmiller86]

Preferred replacement(s), with notes specific to different verticals as required

I wanna make sure I understand what verticals means here. Is this speaking to the situation other participants have mentioned in other meetings where the need for terminology changes varies with communities where it is used? If so, do we understand how these communities are categorized and/or woud it help to consider that? And are verticals only relevant in the context of preferred replacements or in fact is it over-arching the whole of the a particular package of terms and their replacements?

[julian-cable]

A suggested specification for terms:

[status-icon] [term]
[part-of-speech1], [part-of-speech2] [usage-note]

Status icons might be:

Preferred: Green check mark Use with caution: Exclamation mark Do not use: Red cross

Usage note examples might be:

Preferred: Use to refer to ... Write as shown: not "[disallowed-term]". [Justification] Write as shown: two words, lowercase. [Justification] Write as shown: one word, unhyphenated. [Justification] Write as shown, with initial uppercase letter. [Justification]

Use with caution: Use only to refer to ... Otherwise, use [preferred-term]. Do not use to describe ... Do not use in a context where ...

Do not use: Do not use. Use "[preferred-term]". [Justification] Do not use. Use another term, such as "[option-1]" or "[option-2]".

[celestehorgan]

Celeste to create an empty shell (file) for the template and then hand it off to Julian! (email is best)

[julian-cable]

@celestehorgan I have created a template proposal: https://github.com/inclusivenaming/org/pull/64/commits/18d19c9fc0ec8295575341c5309c41ce0bf3e643