Skip to content

Fixes for 7.2 #667

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
julian-cable wants to merge 2 commits into
base: dev
Choose a base branch
from
Open

Fixes for 7.2 #667

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8ee20c2
Fixes for 7.2
julian-cable Jan 15, 2026
a30e652
Fixes to feedback from David
julian-cable Jan 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 38 additions & 26 deletions en-US/A.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,16 @@
<term role="true">AArch64, aarch64</term>
<listitem>
<para>
<emphasis>n.</emphasis> A 64-bit version of the ARM architecture.
Use this term when referring to operating systems and server instances, for example Red&nbsp;Hat Enterprise Linux, Fedora, CoreOS, and other Linux distributions.
<emphasis>n.</emphasis> A 64-bit version of the ARM architecture.
Use this term when referring to operating systems and server instances, for example Red&nbsp;Hat Enterprise Linux, Fedora, CoreOS, and other Linux distributions.
</para>
<para>
Use the uppercase (AArch64) format in general cases when referring to system architecture.
Use the lowercase (aarch64) format only when referring to objects or parameters.
Use the lowercase (aarch64) format only when referring to objects or parameters.
It can be styled as code (monospace font or a code-styled block) when referring to code.
</para>
<para>
Cloud providers might use different formats of this term to refer to architectures.
Cloud providers might use different formats of this term to refer to architectures.
If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
</para>
<para>
Expand Down Expand Up @@ -145,16 +145,16 @@
<term role="true">AMD64, amd64</term>
<listitem>
<para>
<emphasis>n.</emphasis> The AMD 64-bit version of the x86 architecture.
Use this term for Red&nbsp;Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), or command-line interface (CLI) objects.
<emphasis>n.</emphasis> The AMD 64-bit version of the x86 architecture.
Use this term for Red&nbsp;Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), or command-line interface (CLI) objects.
</para>
<para>
Use the uppercase format (AMD64) in general sentences when referring to Red&nbsp;Hat OpenShift Container Platform features.
Use the lowercase format (amd64) only when referring to objects or parameters.
Use the lowercase format (amd64) only when referring to objects or parameters.
It can be styled as code (monospace font or a code-styled block) when referring to code.
</para>
<para>
Cloud providers might use different formats of this term to refer to architectures.
Cloud providers might use different formats of this term to refer to architectures.
If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
</para>
<para>
Expand Down Expand Up @@ -196,16 +196,16 @@
<term role="true">ARM64, arm64</term>
<listitem>
<para>
<emphasis>n.</emphasis> A 64-bit version of the ARM architecture.
Use this term for Red&nbsp;Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), and command-line interface (CLI) objects.
<emphasis>n.</emphasis> A 64-bit version of the ARM architecture.
Use this term for Red&nbsp;Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), and command-line interface (CLI) objects.
</para>
<para>
Use the uppercase format (ARM64) in general sentences when referring to Red&nbsp;Hat OpenShift Container Platform features.
Use lowercase format (arm64) only when referring to objects or parameters.
Use lowercase format (arm64) only when referring to objects or parameters.
It can be styled as code (monospace font or a code-styled block) when referring to code.
</para>
<para>
Cloud providers might use different formats of this term to refer to architectures.
Cloud providers might use different formats of this term to refer to architectures.
If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
</para>
<para>
Expand Down Expand Up @@ -303,7 +303,7 @@
<term>artificial intelligence (AI)</term>
<listitem>
<para>
Unless clarity requires it or the concept is being introduced or explained, "artificial intelligence" does not have to be spelled out on first use; "AI" is understood and suffices. When spelling it out, do not capitalize the term.
Unless clarity requires it or the concept is being introduced or explained, "artificial intelligence" does not have to be spelled out on first use; "AI" is understood and suffices. When spelling it out, do not capitalize the term unless it is part of a proper noun.
</para>

</listitem>
Expand All @@ -319,34 +319,40 @@
<itemizedlist>
<listitem>
<para>
DRaaS (Disaster Recovery-as-a-Service)
AIaaS (Artificial Intelligence-as-a-Service)
Copy link
Collaborator

@daobrien daobrien Jan 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This actually contradicts the previous para: "When spelling it out, do not capitalize the term". You might like to update that para to include "unless part of a proper noun" or similar.

We also do not need all these examples of aaS terms. We need basic guidance and a list of any exceptions, and that's all. Otherwise this list is going to get very long over time.

</para>

</listitem>
<listitem>
<!-- <listitem>
<para>
CaaS (Cloud-as-a-Service, Communications-as-a-Service, <xref linkend="containers-as-a-service" />)
DRaaS (Disaster Recovery-as-a-Service)
</para>

</listitem>
</listitem> -->
<listitem>
<para>
UCaaS (Unified Communications-as-a-Service)
CaaS (Cloud-as-a-Service, Communications-as-a-Service, <xref linkend="containers-as-a-service" />)
</para>

</listitem>
<listitem>
<!-- <listitem>
<para>
FaaS (Functions-as-a-Service)
</para>

</listitem>
</listitem> -->
<listitem>
<para>
SaaS (Search-as-a-Service, Security-as-a-Service, Storage-as-a-Service, or Software-as-a-Service)
IaaS (Infrastructure-as-a-Service)
</para>

</listitem>
<!-- <listitem>
<para>
MaaS (Messaging-as-a-Service, Metal-as-a-Service)
</para>

</listitem> -->
<listitem>
<para>
PaaS (Payments-as-a-Service, Platform-as-a-Service)
Expand All @@ -355,11 +361,11 @@
</listitem>
<listitem>
<para>
MaaS (Messaging-as-a-Service, Metal-as-a-Service)
SaaS (Search-as-a-Service, Security-as-a-Service, Software-as-a-Service, or Storage-as-a-Service)
</para>

</listitem>
<listitem>
<!-- <listitem>
<para>
SECaaS (Security-as-a-Service)
</para>
Expand All @@ -371,6 +377,12 @@
</para>

</listitem>
<listitem>
<para>
UCaaS (Unified Communications-as-a-Service)
</para>

</listitem> -->

</itemizedlist>
<para>
Expand Down Expand Up @@ -400,7 +412,7 @@
</listitem>
<listitem>
<para>
Avoid use of an acronym if it could stand for more than one term in a single asset. for example, if you are writing content that discusses both Cloud-as-a-Service and Containers-as-a-Service.
Avoid using an acronym if it could stand for more than one term in a single asset: for example, if you are writing content that discusses both Cloud-as-a-Service and Containers-as-a-Service.
</para>

</listitem>
Expand All @@ -414,10 +426,10 @@
<term>as Code</term>
<listitem>
<para>
Use camel case for both the full term and the acronym.
Use camel case for both the full term and the acronym.
Do not hyphenate.
Some "as Code" acronyms might overlap.
To avoid confusion, always spell out the full term on first use.
To avoid confusion, always spell out the full term on first use.
</para>
<para>
Examples:
Expand Down
41 changes: 21 additions & 20 deletions en-US/Design.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@
<formalpara id="verbs-titles">
<title>Writing Effective Titles</title>
<para>
Use a title that represents the content.
Use titles that represent the content.
</para>
</formalpara>
<para>
Expand All @@ -63,7 +63,7 @@
In some cases, a verb might not be appropriate because the content is purely informational. Instead of using a vague verb like "Understanding", "Describing", "Introducing", or "Exploring", either use a more specific verb, or use a noun phrase instead of a verb. A noun phrase is descriptive and omits a verb, for example "OpenShift Operators" or "The OpenShift Web Console."
</para>
<para>
Avoid a title that consists of only one word.
Avoid titles that consist of only one word.
</para>
<table>
<title></title>
Expand All @@ -88,12 +88,12 @@
<entry> Introducing Cluster Updates </entry>
<entry> Cluster Updates </entry>

</row>
</row>
<row>
<entry> MetalLB </entry>
<entry> The MetalLB Component </entry>

</row>
</row>

</tbody>

Expand Down Expand Up @@ -486,12 +486,12 @@ $ vi myFile.txt
<listitem>
<para>
On Windows operating systems, use the backtick character (`).
</para>
</para>
</listitem>
<listitem>
<para>
For content that is potentially used in multiple operating systems, use the Linux shell continuation character, and include an explanatory sentence before the command.
</para>
</para>
</listitem>
</itemizedlist>
<!-- <important>
Expand All @@ -502,19 +502,19 @@ $ vi myFile.txt
</important> -->
<para>
Do not use manual line indentation for the second and subsequent lines of commands.
For some output formats, no control is possible over where lines would break, and any indentation might appear as extra spaces in inelegant places.
For some output formats, no control is possible over where lines would break, and any indentation might appear as extra spaces in awkward places.
<!-- You can use this option for any of these designs. -->
</para>

<example><title>Long Command Example</title>
<para>
If the <systemitem>memory</systemitem> machine pool does not exist, then create it.
</para>
</para>
<para>
On a Microsoft Windows system, replace the line continuation character (\) in the following long command with the backtick character (`), which is the line continuation character in PowerShell.
</para>
<screen>$ <userinput>aws iam create-policy --policy-name RosaCloudWatch \ </userinput>
<userinput> --policy-document file://policy.json --query Policy.Arn --output text</userinput>
<userinput>--policy-document file://policy.json --query Policy.Arn --output text</userinput>
arn:aws:iam::452954386616:policy/RosaCloudWatch
</screen>
<para>
Expand All @@ -527,7 +527,8 @@ The ARN in the preceding output is different on your system.
<section id="omitting">
<title>Omitting Part of Output</title>
<para>
For the sake of brevity, do not show all output to the user in all cases, but only those parts of any output that are relevant to the context that is described.
For the sake of brevity, do not show all output to the user in all cases.
Instead, show only those parts of any output that are relevant to the context that is described.
Where output is not included, place a marker to show that information is purposely excluded.
When shortening the output, use a consistent notation.
For omitting entire horizontal lines of output, Red&nbsp;Hat uses the <emphasis>...output&nbsp;omitted...</emphasis> notation, starting and ending with an ellipsis, and highlighted in italics.
Expand Down Expand Up @@ -719,7 +720,7 @@ telemetry-operator.v1.0.0 Telemetry Operator ... -->
If the file to edit is empty or does not exist, do not highlight any content to add.
</para>
<para>
You can also use <systemitem>here</systemitem> documents to describe how to create a file with required content.
You can also use <systemitem>here</systemitem> documents to describe how to create a file with required content.
For more information about <systemitem>here</systemitem> documents, refer to <ulink url="https://tldp.org/LDP/abs/html/here-docs.html" />
The syntax of <systemitem>here</systemitem> documents varies by system, shell, language, and so on. The following example creates the <filename>my-script</filename> file in the current directory, with the example content.
</para>
Expand All @@ -734,7 +735,7 @@ telemetry-operator.v1.0.0 Telemetry Operator ... -->
</para>

</section>

<section id="use-hostnames-correctly">
<title>Using Host and Usernames Correctly</title>
<para>
Expand Down Expand Up @@ -811,13 +812,13 @@ telemetry-operator.v1.0.0 Telemetry Operator ... -->

</formalpara>
<para>
For example, you are the system administrator at Global Banking and you are asked to set up permissions to the accounting directory for the following users: Huong Sabo, Jolene Paluch, Abby Quincy, Francis Ritcher, and Jaya Lamont.
For example, you are the system administrator at Global Banking and you are asked to set up permissions to the accounting directory for the following users: Huong Sabo, Jolene Paluch, Abby Quincy, Francis Ritcher, and Jaya Lamont.
Huong is a department manager and needs read access to the accounting directory. Jolene is the lead accountant and needs both read and write access.
</para>
<formalpara id="choosing-realistic-names">
<title>Choosing a Realistic Name</title>
<para>
Consider the following points when choosing a realistic name:
Consider the following points when choosing a realistic name:
</para>

</formalpara>
Expand Down Expand Up @@ -848,10 +849,10 @@ telemetry-operator.v1.0.0 Telemetry Operator ... -->
Avoid name combinations or abbreviations that result in unintended meanings, such as slang.
An example that works well might be "John Smith", with an email address of <email>jsmith@example.com</email>.
However, for the name "Brian Strong", a corresponding email address of <email>bstrong@example.com</email> might not work so well (when read out, it sounds like "be strong").
Consider also any implications for names in different languages.
Consider also any implications for names in different languages.
</para>
<para>
Refer also to the
Refer also to the
<ulink url="https://developers.google.com/style"><citetitle>Google Developer Documentation Style Guide</citetitle></ulink>.
</para>

Expand Down Expand Up @@ -1000,7 +1001,7 @@ telemetry-operator.v1.0.0 Telemetry Operator ... -->

</table>
<para>
However, in some cases, the sentence might be easier to understand if the noun appears first, or if additional language separates the object name from the noun.
However, in some cases, the sentence might be easier to understand if the noun appears first, or if additional language separates the object name from the noun.
For example, if the noun refers to a password, a value, or a status, then consider stating the noun first, or including explanatory language between the object name and the noun, or doing both.
In other cases, a noun might be omitted.
</para>
Expand Down Expand Up @@ -1182,7 +1183,7 @@ telemetry-operator.v1.0.0 Telemetry Operator ... -->
<title>Capitalization</title>
<para>
Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)".
Not all acronyms are capitalized (for example, "spool"); refer to
Not all acronyms are capitalized (for example, "spool"); refer to
<ulink url="https://www.ibm.com/docs/en/ibm-style?topic=grammar-capitalization"><citetitle>Capitalization</citetitle></ulink> in <citetitle>IBM Style</citetitle>
<guiicon><inlinemediaobject>
<imageobject>
Expand All @@ -1195,7 +1196,7 @@ telemetry-operator.v1.0.0 Telemetry Operator ... -->
<formalpara id="articles">
<title>Articles</title>
<para>
When deciding which articles to use, consider pronunciation.
When deciding which articles to use, consider pronunciation.
For example, use "an <abbrev>RTS</abbrev> (real-time strategy)", because <abbrev>RTS</abbrev> is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a <acronym>RAM</acronym> upgrade", because <acronym>RAM</acronym> is an acronym and you pronounce it as a word (răm).
</para>
</formalpara>
Expand Down Expand Up @@ -1559,7 +1560,7 @@ Publication Title by First name Surname; Publisher.
</listitem>
<listitem>
<para>
If the URL is long or complex, then create a link by using the title of the destination as a label, and put the URL in a footnote.
If the URL is long or complex, then create a link by using the title of the destination as a label, and put the URL in a footnote.
For example: Refer to the <ulink url="https://www.britannica.com/animal/mammal/Classification"><citetitle>Classification of Species</citetitle></ulink><footnote> <para>
<ulink url="https://www.britannica.com/animal/mammal/Classification" />
</para>
Expand Down
Loading