[[grammar]]
= Grammar and language

[[conscious-language]]
== Conscious language

The Conscious Language Group supports the Red{nbsp}Hat commitment to remove problematic language from our code, documentation, websites, and open source projects with which Red{nbsp}Hat is involved.
For more information about the Conscious Language Group, see https://github.com/conscious-lang/conscious-lang-docs.

[IMPORTANT]
====
To ensure consistency and success, it is imperative for product team stakeholders to align internally. For example, documentation teams should engage in discussions with their engineering leadership to reach an agreement on replacement terms. This ensures that the product documentation matches the code.
====

=== Blacklist and whitelist

When possible, rewrite documentation to avoid these terms.
When it is not possible to remove the terms _blacklist_ and _whitelist_, replace them with one of the following alternatives:

* Blocklist / allowlist: This combination is recommended by the _IBM Style_ guide. Use this combination unless your product area has another specific replacement that is agreed between engineering leadership and your documentation team.
* Denylist / allowlist
* Blocklist / passlist
* You can also use a term that has been agreed by your product team stakeholders.

.Examples
* Removing blacklist
+
image:images/no.png[no] Heat _blacklists_ any servers in the list from receiving updated heat deployments. After the stack operation completes, any blacklisted servers remain unchanged. You can also power off or stop the `os-collect-config` agents during the operation.
+
image:images/yes.png[yes] Heat _excludes_ any servers in the list from receiving updated heat deployments. After the stack operation completes, any excluded servers remain unchanged. You can also power off or stop the `os-collect-config` agents during the operation.

* Removing whitelist
+
image:images/no.png[no] The following steps demonstrate adding a new rule to _whitelist_ a custom binary.
+
image:images/yes.png[yes] The following steps demonstrate adding a new rule to _allow_ a custom binary.


=== Master and slave

When possible, rewrite documentation to avoid these terms. When it is not possible to rewrite, you can use the following alternatives for _master_ / _slave_:

* Primary / secondary
* Source / replica
* Initiator, requester / responder
* Controller, host / device, worker, proxy
* Director / performer
* Controller / port interface (in networking)
* You can also use a term that has been agreed by your product team stakeholders.


.Examples
* Removing _master_
+
image:images/no.png[no] A Ceph Monitor maintains the _master_ copy of the Red{nbsp}Hat Ceph Storage cluster map with the current state of the Red{nbsp}Hat Ceph Storage cluster.
+
image:images/yes.png[yes] A Ceph Monitor maintains the _primary_ copy of the Red{nbsp}Hat Ceph Storage cluster map with the current state of the Red{nbsp}Hat Ceph Storage cluster.
+
image:images/yes.png[yes] A Ceph Monitor maintains the _main_ copy of the Red{nbsp}Hat Ceph Storage cluster map with the current state of the Red{nbsp}Hat Ceph Storage cluster.


* Removing _slave_
+
image:images/no.png[no] Use the following command to copy the public key to the _slave_ node.
+
image:images/yes.png[yes] Use the following command to copy the public key to the _secondary_ node.

[[contractions]]
== Contractions

Avoid contractions in product documentation to leave no ambiguity and to make it easier for translation and international audiences.

If you are writing quick start or other content that uses a more informal xref:#conversational-style[conversational style] (_fairly conversational_ or _more conversational_), you may use contractions. In this case, follow the guidance in the _IBM Style_ guide on using contractions.

[[conversational-style]]
== Conversational style

Follow the _IBM Style_ guide advice of _less conversational_ style in most cases.

.Example: Less conversational style

Red{nbsp}Hat Enterprise Linux 8 delivers a stable, secure, and consistent foundation across hybrid cloud deployments with the tools needed to deliver workloads faster with less effort.

As needed, adjust the conversational to _fairly conversational_ for an audience of new users or _least conversational_ for API documentation and other very experienced audiences.

[NOTE]
====
Documentation for cloud services follows the _IBM Style_ guide for _fairly conversational_ tone. When using _fairly conversational_ tone, use contractions where appropriate.
====

[[homographs]]
== Homographs
A homograph is a word that is spelled the same as another word but has a different meaning.
Using homographs close together in a sentence or paragraph might confuse readers.
Therefore, be aware of this potential issue, and, when possible, avoid writing sentences that use homographs close to one another provided that you can do so without changing the technical meaning.

The following list includes homographs that might commonly appear in technical documentation:

* Application
* Attribute
* Block
* Coordinates
* Number
* Object
* Project

[[minimalism]]
== Minimalism
Minimalism is a methodology for creating targeted documentation focused on your readers' needs. If you understand your customers' needs, you can write shorter and simpler documentation specific to what customers want to do.

Minimalism has five principles:

=== Principle 1: Customer focus and action orientation
Know what your users do, what their goals are, and why they perform these actions. Minimize how much content customers must wade through to get to something they recognize as real work. Separate conceptual and background information from procedural tasks.

=== Principle 2: Findability
Findability covers two areas:

* Ensure your content is findable through Google search and access.redhat.com site searches.
* Ensure your content is scannable. Use short paragraphs and sentences and bulleted lists where appropriate.

=== Principle 3: Titles and headings
Use clear titles with familiar keywords for customers. Keep titles and headings between 3 to 11 words. Headings that are too short lack clarity and don’t help customers know what’s in a section. Headings that are too long are less visible in Google searches and harder for customers to understand.

=== Principle 4: Elimination of fluff
Avoid long introductions and unnecessary context. Shorten unnecessarily long sentences.

=== Principle 5: Error recovery, verification, and troubleshooting
Recognize that people make mistakes and need to verify that they have completed a task. Be sure to include troubleshooting, error recovery, and verification steps.

[[users]]
== Users
In most cases, the word "user" refers to a person or a person's user account, and therefore would be considered animate. In these cases, use animate personal pronouns such as "who".

In certain technical cases, these users are not persons but instead system accounts or more abstract concepts (inanimate). For example, Linux `root` and `guest` users do not relate to any person. Applications and services might run as specific Linux users with no person controlling them. SELinux users such as `user_u` or `sysadm_u` are identifiers of one or multiple Linux users for access control purposes. In these specific cases, refer to these inanimate users with inanimate personal pronouns such as "that".

In these specific cases, and only if you cannot write around it, you can refer to these inanimate users with inanimate personal pronouns such as "that".

.Examples
* Animate user
+
image:images/no.png[no] Experienced _users that_ can configure their own systems...
+
image:images/yes.png[yes] _Users who_ want to install their own packages...

* Inanimate user
+
image:images/no.png[no] A Linux user has the restrictions of the _SELinux user who_ it is assigned to.
+
image:images/no.png[no] A Linux user has the restrictions of the _SELinux user_ to _whom_ it is assigned.
+
image:images/yes.png[yes] Specify a _user that_ is allowed to perform the requested action.
+
image:images/yes.png[yes] A Linux user has the restrictions of the _SELinux user that_ it is assigned to.


// TODO: Add new style entries alphabetically in this file