Merge pull request #439 from rolfedh/on-first-use

Standardize on "the first use"

Author: sbmetz

GUIDELINES.adoc

@@ -33,7 +33,7 @@ Use the following template for glossary entries:
 * `\image:images/caution.png[with caution]`
 |`<term>`               |The term to be described.          |
 |`<class>`              |The part of speech of the term.|Possible values: noun, verb, adjective, adverb, pronoun, conjunction, preposition. Use noun for acronyms or abbreviations. Leave the field empty for symbols.
-|`<description>`        |The description of the term.|Use full sentences with periods. If a term is specific to a particular product, start the description with "In <product_name>,". If a term has more than one meaning, use numbers to separate them. For example: (1) <first_meaning>. (2) <second_meaning>. Add information about why we should or shouldn't use the term in this form. Alternatively, explain why the terms listed in the *Incorrect forms* field are incorrect.
+|`<description>`        |The description of the term.|Use full sentences with periods. If a term is specific to a particular product, start the description with "In <product_name>,". If a term has multiple meanings, use numbers to separate them. For example: (1) <first_meaning>. (2) <second_meaning>. Add information about why we should or shouldn't use the term in this form. Alternatively, explain why the terms listed in the *Incorrect forms* field are incorrect.
 |`<yes/no/with caution>`|"yes" if the term should be used.
 
 "no" if the term should not be used.
@@ -49,7 +49,7 @@ Use the following template for glossary entries:
 
 * Keep all fields, even if a field is empty. An empty field serves as a placeholder if the field is required later.
 
-* Use quotation marks on the first occurrence of a term in the *Description* field. Do not include an abbreviation in parentheses within the quotation marks; for example, "Asynchronous Transfer Mode" (ATM) is a network technology based on transferring data in cells or packets of a fixed size.
+* Use quotation marks on first use of a term in the *Description* field. Do not include an abbreviation in parentheses within the quotation marks; for example, "Asynchronous Transfer Mode" (ATM) is a network technology based on transferring data in cells or packets of a fixed size.
 
 * If the *Description* field contains more than one paragraph, only the last paragraph is displayed in the Atom linter's text. Ensure that word usage advice is contained in the last paragraph.
 
@@ -59,7 +59,7 @@ Use the following template for glossary entries:
 
 * If you want to add a term that we should not use and that does not have a correct form, use the incorrect version instead of `<term>` and add "no" to the *Use it* field. Explain why we should not use that term in the *Description* field.
 
-* When creating IDs in accordance with the rules described in the template, the resulting IDs might be the same as those for separate entries. For example, the "kernel space" and "kernel-space" entries, or the "kB" and "KB" entries would have the same anchor tag ("kernel-space" and "kb"). If the IDs are not unique, however, it will cause an error in the document.
+* Creating an ID according to guidance in the template can produce duplicate IDs for distinct entries. For example, the IDs for the "kernel space" and "kernel-space" entries would both be "kernel-space". Similarly, the IDs for the "kB" and "KB" entries would be "kb". Duplicate IDs in a document lead to build errors.
 +
 To avoid this issue, use different IDs:
 +
@@ -136,4 +136,4 @@ Use the following template when adding a new style guide entry:
 
 * Use double quotation marks ("") when emphasizing how to write a term. The following examples demonstrate the use of this guideline:
 ** Hyphenate "look-up" when using it as a modifier.
-** Spell out "comma-separated values" on first use; use "CSV" thereafter.
+** Write "comma-separated values (CSV)" on first use and "CSV" after that.

supplementary_style_guide/glossary_terms_conventions/general_conventions/a.adoc

@@ -58,7 +58,7 @@ _Specify the system architecture of your cluster, such as `x86_64` or `aarch64`.
 // RHDS: General; kept as is
 [[access-control-instruction]]
 ==== image:images/yes.png[yes] access control instruction (noun)
-*Description*: In an LDAP directory, an _access control instruction (ACI)_ grants or denies access to entries or attributes. Use "access control instruction" on the first usage and then the abbreviation "ACI" subsequently.
+*Description*: In an LDAP directory, an _access control instruction (ACI)_ grants or denies access to entries or attributes. Write "access control instruction (ACI)" on first use and "ACI" after that.
 
 *Use it*: yes
 
@@ -81,7 +81,7 @@ _Specify the system architecture of your cluster, such as `x86_64` or `aarch64`.
 
 [[ack]]
 ==== image:images/no.png[no] ACK (noun)
-*Description*: Do not use _ACK_ as acronym for "acknowledgement" in general. When writing about the acknowledgement flag ("ACK flag") in a TCP packet, use "ACK flag".
+*Description*: Do not use _ACK_ as an abbreviation for "acknowledgment". When writing about the acknowledgment flag ("ACK flag") in a TCP packet, use "ACK flag".
 
 *Use it*: no
 
@@ -92,7 +92,7 @@ _Specify the system architecture of your cluster, such as `x86_64` or `aarch64`.
 
 [[ack-flag]]
 ==== image:images/yes.png[yes] ACK flag (noun)
-*Description*: The acknowledgement flag (_ACK flag_) in a TCP packet indicates that the acknowledgement field in the packet is relevant. Do not expand on first usage and write as shown: "ACK flag".
+*Description*: The acknowledgment flag (_ACK flag_) in a TCP packet indicates that the acknowledgment field in the packet is relevant. Do not expand the abbreviation on first use. Write "ACK flag".
 
 *Use it*: yes
 

supplementary_style_guide/glossary_terms_conventions/general_conventions/b.adoc

@@ -93,7 +93,7 @@
 ==== image:images/yes.png[yes] Basic HTTP authentication (noun)
 *Description*: _Basic HTTP authentication_, or _Basic authentication_, is an authorization scheme that uses HTTP to send login credentials encoded in Base64.
 This scheme is often used by applications to authenticate with servers, services, and API endpoints.
-On first use, use "Basic HTTP authentication"; thereafter, use "Basic authentication".
+Write "Basic HTTP authentication" on first use and "Basic authentication" after that.
 
 *Use it*: yes
 
@@ -116,7 +116,7 @@ On first use, use "Basic HTTP authentication"; thereafter, use "Basic authentica
 // EAP: Added "In Red Hat JBoss Enterprise Application Platform,"
 [[batch-jberet]]
 ==== image:images/yes.png[yes] batch-jberet subsystem (noun)
-*Description*: In Red Hat JBoss Enterprise Application Platform, the _batch-jberet subsystem_ is used to configure and manage batch jobs. In general text, write in lowercase as two words separated by a hyphen. Use "Batch subsystem" when referring to the `batch-jberet` subsystem in titles and headings.
+*Description*: In Red Hat JBoss Enterprise Application Platform, the _batch-jberet subsystem_ is used to configure and manage batch jobs. In general text, write in lowercase as two words separated by a hyphen. Write "Batch subsystem" when referring to the `batch-jberet` subsystem in titles and headings.
 
 *Use it*: yes
 
@@ -128,7 +128,7 @@ On first use, use "Basic HTTP authentication"; thereafter, use "Basic authentica
 // EAP: Added "In Red Hat JBoss Enterprise Application Platform,"
 [[bean-validation]]
 ==== image:images/yes.png[yes] bean-validation subsystem (noun)
-*Description*: In Red Hat JBoss Enterprise Application Platform, the _bean-validation subsystem_ is used to configure validation of Java bean object data. In general text, write in lowercase as two words separated by a hyphen. Use "Bean Validation subsystem" when referring to the `bean-validation` subsystem in titles and headings.
+*Description*: In Red Hat JBoss Enterprise Application Platform, the _bean-validation subsystem_ is used to configure validation of Java bean object data. In general text, write in lowercase as two words separated by a hyphen. Write "Bean Validation subsystem" when referring to the `bean-validation` subsystem in titles and headings.
 
 *Use it*: yes
 
@@ -174,7 +174,7 @@ The practice of having both modes together is often referred to as _hybrid_, _ag
 
 [[bind]]
 ==== image:images/yes.png[yes] BIND (noun)
-*Description*: Use "BIND" when referring to the DNS software.
+*Description*: Write "BIND" when referring to the DNS software.
 
 *Use it*: yes
 
@@ -197,9 +197,9 @@ The practice of having both modes together is often referred to as _hybrid_, _ag
 
 [[bios]]
 ==== image:images/caution.png[with caution] BIOS (noun)
-*Description*: _BIOS_ is an abbreviation for "Basic Input/Output System". The plural form is "BIOSes". BIOS is the specific name for the motherboard firmware that provides runtime services for operating systems in older PCs. Modern computers use a different kind of firmware, called either EFI or UEFI.
+*Description*: _BIOS_ is an abbreviation for "Basic Input/Output System". The plural form is "BIOSes". BIOS is the specific name for the system board firmware that provides runtime services for operating systems in older PCs. Modern computers use a different kind of firmware, called either EFI or UEFI.
 
-Do not use "BIOS" as a generic term to refer to computer firmware. Use "firmware" or a specific phrase such as "UEFI firmware" or "legacy BIOS" instead.
+Do not use "BIOS" as a generic term for computer firmware. Instead, write "firmware" or a specific phrase such as "UEFI firmware" or "legacy BIOS".
 
 *Use it*: with caution
 
@@ -474,7 +474,7 @@ Do not use "BIOS" as a generic term to refer to computer firmware. Use "firmware
 
 [[built-in]]
 ==== image:images/yes.png[yes] built-in (adjective)
-*Description*: Use "built-in" when referring to something that is included or incorporated into a larger unit.
+*Description*: Write "built-in" when referring to something that is included or incorporated into a larger unit.
 
 *Use it*: yes
 

supplementary_style_guide/glossary_terms_conventions/general_conventions/c.adoc

@@ -38,7 +38,7 @@
 // Satellite: Added "In Red Hat Satellite"
 [[capsule-server]]
 ==== image:images/yes.png[yes] Capsule Server (noun)
-*Description*: In Red Hat Satellite, _Capsule Server_ is an additional server that acts as a proxy to the Satellite and can provide services such as DHCP, DNS, and TFTP. Use the two-word name on first use in a section; the single term 'Capsule' is acceptable thereafter.
+*Description*: In Red Hat Satellite, _Capsule Server_ is an additional server that acts as a proxy to the Satellite and can provide services such as DHCP, DNS, and TFTP. Write "Capsule Server" on first use. "Capsule" is acceptable after that.
 
 *Use it*: yes
 
@@ -287,7 +287,7 @@
 
 [[cidr]]
 ==== image:images/yes.png[yes] CIDR (noun)
-*Description*: Classless Inter-Domain Routing (_CIDR_) is a method to efficiently allocate IP addresses and for IP routing. CIDR replaces the classful network addressing architecture. In CIDR notation, IP addresses contain a suffix that represents the number of bits of the prefix. Expand on first usage, and write it as shown: "Classless Inter-Domain Routing".
+*Description*: Classless Inter-Domain Routing (_CIDR_) is a method to efficiently allocate IP addresses and for IP routing. CIDR replaces the classful network addressing architecture. In CIDR notation, IP addresses contain a suffix that represents the number of bits of the prefix. Write "Classless Inter-Domain Routing (CIDR)" on first use and "CIDR" after that.
 
 *Use it*: yes
 
@@ -469,7 +469,7 @@
 
 [[comma-separated-values]]
 ==== image:images/yes.png[yes] comma-separated values (noun)
-*Description*: _Comma-separated values_ are a set of values in which each value is separated by a comma. Spell out "comma-separated values" on first use; use "CSV" thereafter.
+*Description*: _Comma-separated values_ are a set of values in which each value is separated by a comma. Write "comma-separated values (CSV)" on first use and "CSV" after that.
 
 *Use it*: yes
 
@@ -540,7 +540,7 @@
 // Satellite: Added "In Red Hat Satellite"
 [[composite-content-view]]
 ==== image:images/yes.png[yes] Composite Content View (noun)
-*Description*: In Red Hat Satellite, a _Composite Content View_ is a collection of Content Views. Use the three-word name in full on first use in a section; the abbreviation "CCV" is acceptable thereafter.
+*Description*: In Red Hat Satellite, a _Composite Content View_ is a collection of Content Views. Write "Composite Content View (CCV)" on first use and "CCV" after that.
 
 *Use it*: yes
 
@@ -729,7 +729,7 @@ image repository contains one or more tagged images.
 // Satellite: Added "In Red Hat Satellite"
 [[content-view]]
 ==== image:images/yes.png[yes] Content View (noun)
-*Description*: In Red Hat Satellite, a _Content View_ is a subset of Library content created by intelligent filtering. Use the two-word name in full on first use in a section; the abbreviation "CV" is acceptable thereafter.
+*Description*: In Red Hat Satellite, a _Content View_ is a subset of Library content created by intelligent filtering. Write "Content View (CV)" on first use and "CV" after that.
 
 *Use it*: yes
 
@@ -961,7 +961,7 @@ With a _cross-forest trust_ between an Active Directory (AD) forest root domain
 
 [[csv]]
 ==== image:images/yes.png[yes] CSV (noun)
-*Description*: _CSV_ is an abbreviation for "comma-separated values", which is a set of values in which each value is separated by a comma. Spell out "comma-separated values" on first occurrence; use "CSV" thereafter.
+*Description*: _CSV_ is an abbreviation for "comma-separated values", which is a set of values in which each value is separated by a comma. Write "comma-separated values (CSV)" on first use and "CSV" after that.
 
 *Use it*: yes
 
@@ -1029,7 +1029,7 @@ With a _cross-forest trust_ between an Active Directory (AD) forest root domain
 
 [[customer-portal]]
 ==== image:images/caution.png[with caution] Customer Portal (noun)
-*Description*: _Customer Portal_ is the shortened form of "Red Hat Customer Portal", the official name for https://access.redhat.com. Use "Red Hat Customer Portal" on the first use. You can shorten it to "Customer Portal" after that.
+*Description*: _Customer Portal_ is the shortened form of "Red Hat Customer Portal", the official name for https://access.redhat.com. Write "Red Hat Customer Portal" on first use. You can shorten it to "Customer Portal" after that.
 
 *Use it*: with caution
 

supplementary_style_guide/glossary_terms_conventions/general_conventions/e.adoc

@@ -195,7 +195,7 @@ If referring to the program, use "Emacs", for example, "Source-Navigator support
 
 [[executable]]
 ==== image:images/caution.png[with caution] executable (noun)
-*Description*: When it runs, an _executable_ performs specific operations based on its coded instructions. Write "executable file (executable)" on the first use.
+*Description*: When it runs, an _executable_ performs specific operations based on its coded instructions. Write "executable file (executable)" on first use.
 
 *Use it*: with caution
 

supplementary_style_guide/glossary_terms_conventions/general_conventions/h.adoc

@@ -22,7 +22,7 @@
 
 [[hashbang]]
 ==== image:images/no.png[no] hashbang (noun)
-*Description*: Do not use _hashbang_ when referring to a computer language construct that controls which interpreter parses and interprets instructions in a computer program. Instead, on the first mention, include both "interpreter directive" and "shebang", for example, "Interpreter directives, also known as shebangs ...".
+*Description*: Do not use _hashbang_ when referring to a computer language construct that controls which interpreter parses and interprets instructions in a computer program. Write "interpreter directives, also known as shebangs ..." on first use.
 
 *Use it*: no
 

supplementary_style_guide/glossary_terms_conventions/general_conventions/i.adoc

@@ -556,7 +556,7 @@ Red Hat Trusted Application Pipeline users can configure secrets to inject sensi
 
 [[intel-virtualization-technology]]
 ==== image:images/yes.png[yes] Intel Virtualization Technology (noun)
-*Description*: The first and all prominent uses of _Intel Virtualization Technology_ should be spelled out, immediately followed by the abbreviation, for example, "Intel Virtualization Technology (Intel VT) for Intel 64" or "Itanium architecture (Intel VT-i)". Subsequent uses can be abbreviated to "Intel VT-i". Always write the abbreviation in uppercase letters, accompanied by the Intel mark. Do not use the abbreviation in any prominent places, such as in titles or paragraph headings. Do not include any trademark symbols, such as "(TM)" or "\(TM)".
+*Description*: Write "Intel Virtualization Technology (Intel VT)" or "Itanium architecture (Intel VT-i)" on first use and then "Intel VT" or "Intel VT-i" after that. Do not use the abbreviation in prominent places such as in titles or paragraph headings. Do not include trademark symbols such as "(TM)" or "\(TM)".
 
 *Use it*: yes
 
@@ -629,7 +629,7 @@ _This feature can run only on Intel 64 processors_
 
 [[interpreter-directive]]
 ==== image:images/yes.png[yes] interpreter directive (noun)
-*Description*: An _interpreter directive_, such as `#!/bin/bash`, is a computer language construct that controls which interpreter parses and interprets instructions in a computer program. This term is also commonly known as _shebang_. On the first mention, include both "interpreter directive" and "shebang", for example, "Interpreter directives, also known as shebangs ...". Do not use "hashbang".
+*Description*: An _interpreter directive_, such as `#!/bin/bash`, is a computer language construct that controls which interpreter parses and interprets instructions in a computer program. This term is also commonly known as _shebang_. Write "interpreter directives, also known as shebangs ..." on first use. Do not use "hashbang".
 
 *Use it*: yes
 
@@ -674,7 +674,7 @@ _This feature can run only on Intel 64 processors_
 
 [[ip]]
 ==== image:images/yes.png[yes] IP (noun)
-*Description*: _IP_ is an abbreviation for "Internet Protocol". Use "IP" to refer to the Internet Protocol in general if the specific versions, IPv4 and IPv6, do not matter. Use "IP address" instead of "IP" when writing about IP addresses. Do not expand the abbreviation on the first usage.
+*Description*: _IP_ is an abbreviation for "Internet Protocol". Use "IP" to refer to the Internet Protocol in general if the specific versions, IPv4 and IPv6, do not matter. Use "IP address" instead of "IP" when writing about IP addresses. Do not expand the abbreviation on first use.
 
 *Use it*: yes
 
@@ -696,7 +696,7 @@ _This feature can run only on Intel 64 processors_
 
 [[ipv4]]
 ==== image:images/yes.png[yes] IPv4 (noun)
-*Description*: Use _IPv4_ to explicitly refer to version 4 of the Internet Protocol. Do not expand the abbreviation on the first usage.
+*Description*: Use _IPv4_ to explicitly refer to version 4 of the Internet Protocol. Do not expand the abbreviation on first use.
 
 *Use it*: yes
 
@@ -707,7 +707,7 @@ _This feature can run only on Intel 64 processors_
 
 [[ipv6]]
 ==== image:images/yes.png[yes] IPv6 (noun)
-*Description*: Use _IPv6_ to explicitly refer to version 6 of the Internet Protocol. Do not expand the abbreviation on the first usage.
+*Description*: Use _IPv6_ to explicitly refer to version 6 of the Internet Protocol. Do not expand the abbreviation on first use.
 
 *Use it*: yes
 

supplementary_style_guide/glossary_terms_conventions/general_conventions/k.adoc

@@ -183,7 +183,7 @@ Do not capitalize the first letter.
 
 [[kernel-based-virtual-machine]]
 ==== image:images/yes.png[yes] Kernel-based Virtual Machine (noun)
-*Description*: _Kernel-based Virtual Machine_ is a loadable kernel module that converts the Linux kernel into a bare-metal hypervisor. Spell out "Kernel-based Virtual Machine" on first occurrence, and use "KVM" thereafter. It is an industry standard and a proper noun.
+*Description*: _Kernel-based Virtual Machine_ is a loadable kernel module that converts the Linux kernel into a bare-metal hypervisor. Write "Kernel-based Virtual Machine (KVM)" on first use and "KVM" after that. It is an industry standard and a proper noun.
 
 *Use it*: yes