Use of terms from other domains, eg. databases, in documentation

[Christopher De Vries]

In some cases kubernetes documentation uses terms from other projects which are objectionable and in many cases are in the process of being changed within those projects. A good example are the terms master and slave in the MySQL StatefulSet example here: https://kubernetes.io/docs/tasks/run-application/run-replicated-stateful-application/.

I submitted pull request 23119 to kubernetes/website to change the term "master" to "primary" and "slave" to "secondary" before learning about the naming committee. In the last meeting I offered to open a thread to discuss situations like this so we can come up with a recommendation.

My initial recommendation would be to use the new terms adopted by the project we are referencing when referring to external projects, if they are adopting new terms. In the case of the MySQL example, it appears they are in the process of adopting the terms source and replica to replace master and slave (see https://mysqlhighavailability.com/mysql-terminology-updates/ ). The transition is underway, but incomplete, and many of the commands do not yet reflect the new terms. Other databases are choosing different terms, for example MariaDB seems to be converging on primary and replica (see https://jira.mariadb.org/browse/MDEV-18777 ), and has added the alias "replica" to replace "slave" in replication commands. 

For projects which are not changing their terms, it may be worthwhile to use Microsoft's style guide as a basis for our documentation and reference the fact that the project uses the more offensive term in their own documentation. Microsoft has a number of alternatives including primary and replica, though they note that the terms are context dependent (see https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/m/master-slave). I would put forward that we should use primary and replica to refer to replicated database setups in the absence of project-specific guidance. 

So in summary, I would like feedback on the following suggestion:

1. Adopt new terms from other projects when referring to those projects.

2. In the absence of new terminology use primary and replica when describing replicated SQL database setups.

Chris

[Celeste Horgan]

Hi Chris,

Thank you for taking this to the mailing list. Let me first address your recommendations.

1. Adopt new terms from other projects when referring to those projects.

I agree with this approach so long as the project has actually converged on a term.

2. In the absence of new terminology use primary and replica when describing replicated SQL database setups.

Hmm. I think this also makes sense but...

What #2 on your list makes me think is that we maybe need an overall set of guiding principles/recommendations (i.e. "In absence of new terminology in a referenced project, use x") for this rather than tacking these on to individual recommendations.

I'm happy to move ahead with using primary/replica in http://github.com/kubernetes/website/pull/23119. I'll provide a review/lgtm and unblock it after sending this message.

Does anyone have additional comments?

Celeste