Skip to content

daobrien/457 vale check #464

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

Merged
daobrien merged 3 commits into from
Feb 8, 2023
Merged

daobrien/457 vale check #464

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d82ff7a
Working on #457 Run Vale of the style guide part 3.
Feb 2, 2023
2733a9c
Closes #457 Run Vale over the style guide, part 3.
Feb 3, 2023
06426b0
Remove spurious space.
Feb 6, 2023
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
30 changes: 21 additions & 9 deletions en-US/M.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,13 @@
</listitem>

</varlistentry>
<!-- Added for inclusive language -->
<varlistentry id="master">
<term>master</term>
<listitem>
<para>
Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use another term such as "main", "primary", "controller", or "leader".
Do not use "master" when it is paired with "slave".
Such use diminishes the horror of the dehumanizing practice of slavery.
Use another term such as "main", "primary", "controller", or "leader".
</para>
<para>
Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill.
Expand All @@ -58,7 +59,9 @@
<term>matrixes</term>
<listitem>
<para>
Correct. This is the correct plural form for US English spelling. Do not use "matrices".
Correct.
This is the correct plural form for US English spelling.
Do not use "matrices".
</para>
<!-- "US" without periods? -->

Expand Down Expand Up @@ -125,18 +128,20 @@
<para>
Objects on which data can be stored. These include hard disks, CDs, and tapes.
</para>
<!-- Deleted "diskettes". -->

</listitem>
<listitem>
<para>
In computer networks, "media" refers to the cables that link workstations together. Out of many types of transmission media, the most popular are twisted-pair wire (normal electrical wire), coaxial cable (the type of cable used for cable television), and fiber optic cable (cables made out of glass).
In computer networks, "media" refers to the cables that link workstations together.
Out of many types of transmission media, the most popular are twisted-pair wire (normal electrical wire), coaxial cable (the type of cable used for cable television), and fiber optic cable (cables made out of glass).
<!-- This is way out of date and needs revision -->
</para>

</listitem>
<listitem>
<para>
The form and technology to communicate information. Multimedia presentations, for example, combine sound, pictures, and videos, all of which are different types of media.
The form and technology to communicate information.
Multimedia presentations, for example, combine sound, pictures, and videos, which are all different types of media.
</para>

</listitem>
Expand Down Expand Up @@ -254,7 +259,10 @@
<term>mouse button</term>
<listitem>
<para>
<emphasis>n.</emphasis> Two words. Do not use "mouse-button" or "mousebutton". If you need to indicate which mouse button, use "right", "left", or "center", such as "right mouse button". Do not hyphenate.
<emphasis>n.</emphasis> Two words.
Do not use "mouse-button" or "mousebutton".
If you need to indicate which mouse button, use "right", "left", or "center", such as "right mouse button".
Do not hyphenate.
</para>

</listitem>
Expand All @@ -264,7 +272,9 @@
<term>Mozilla Firefox</term>
<listitem>
<para>
Correct. First reference must be "Mozilla Firefox". Subsequent references can be "Firefox".
Correct.
The first reference must be "Mozilla Firefox".
Any following references can be "Firefox".
</para>

</listitem>
Expand All @@ -274,7 +284,9 @@
<term>Mozilla Thunderbird</term>
<listitem>
<para>
Correct. First reference must be "Mozilla Thunderbird". Subsequent references can be "Thunderbird".
Correct.
The first reference must be "Mozilla Thunderbird".
Any following references can be "Thunderbird".
</para>

</listitem>
Expand Down
22 changes: 12 additions & 10 deletions en-US/N.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@
<term>navigate to</term>
<listitem>
<para>
Use "Navigate to" when moving through multiple UI options, because it covers all cases where you might have to click, point to, select, or otherwise make a series of selections to initiate an action. For example, "From the OpenShift web console, navigate to Monitoring → Alerting."
Use "Navigate to" when moving through multiple UI options, because it covers all cases where you might have to click, point to, select, or otherwise make a series of selections to initiate an action.
For example, "From the OpenShift web console, navigate to Monitoring → Alerting."
</para>
<para>
Do not use "Go to", or "point to", or other variations.
Expand All @@ -22,7 +23,8 @@
<term>needs, needs to be, need to</term>
<listitem>
<para>
Avoid when possible. Suggested alternatives include "must" or "required".
Avoid when possible.
Use "must" or "required" or similar.
</para>

</listitem>
Expand Down Expand Up @@ -56,10 +58,13 @@
<term>NFS</term>
<listitem>
<para>
Abbreviation of Network File System, a client/server application designed by Sun Microsystems that provides access for all network users to shared files stored on computers of different types. NFS provides access to shared files through the Virtual File System (VFS) interface that runs in a layer above TCP/IP. Users can manipulate shared files as if they were stored locally on the user's own hard disk.
Abbreviation of Network File System, a client/server application designed by Sun Microsystems that provides access for all network users to shared files stored on computers of different types.
NFS provides access to shared files through the Virtual File System (VFS) interface that runs in a layer above TCP/IP.
Users can manipulate shared files as if they were stored locally on the user's own hard disk.
</para>
<para>
With NFS, computers that are connected to a network operate as clients while accessing remote files, and as servers while providing remote users access to local shared files. The NFS standards are publicly available and widely used.
With NFS, computers that are connected to a network operate as clients while accessing remote files, and as servers while providing remote users access to local shared files.
The NFS standards are publicly available and widely used.
</para>

</listitem>
Expand Down Expand Up @@ -111,17 +116,14 @@
<term>number sign</term>
<listitem>
<para>
Generally, use "number sign" to refer to the # character. Alternatively, use "hash" to refer to a hashtag in social media, or to refer to Secure Hash Algorithm (see <xref linkend="sha" />), or when writing exclusively for a European audience. You can instead use "pound sign" when writing exclusively for a North American audience, if "number sign" is not appropriate for the context.
Generally, use "number sign" to refer to the # character.
Or, use "hash" to refer to a hashtag in social media, or to refer to Secure Hash Algorithm (see <xref linkend="sha" />), or when writing exclusively for a European audience.
Copy link
Copy Markdown
Collaborator

@julian-cable julian-cable Feb 3, 2023

Choose a reason for hiding this comment

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

I know that Microsoft advises otherwise, but I don't much like this word replacement at the start of this sentence, which results in a sentence in the format "Or A, or B, or C".

You can instead use "pound sign" when writing exclusively for a North American audience, if "number sign" is not appropriate for the context.
</para>

</listitem>

</varlistentry>

<!-- Moved "Numbers" entry to Chapter 4. -->
<!-- <varlistentry id="numbers">
<term>numbers</term>
</varlistentry> -->

</variablelist>
</chapter>
44 changes: 27 additions & 17 deletions en-US/O.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,15 +51,13 @@
<term>offline backup</term>
<listitem>
<para>
Correct. Use this term to refer to backing up a database while the database is not being accessed by applications. Do not use "cold backup" or any other variations.
Correct.
Use this term to refer to backing up a database while the database is not being accessed by applications.
Do not use "cold backup" or any other variations.
</para>
<para>
The counterpart to this term is "online backup", to refer to the process of backing up a database while it is being accessed by other applications. Do not use "hot backup" or any other variations.
<!-- Deleted footnote: URL is no longer valid. -->
<!-- <footnote> <para>
<ulink url="http://www-01.ibm.com/software/globalization/terminology/o.html" />
</para>
</footnote> -->
The counterpart to this term is "online backup", to refer to the process of backing up a database while it is being accessed by other applications.
Do not use "hot backup" or any other variations.
</para>

</listitem>
Expand All @@ -69,12 +67,13 @@
<term>OK</term>
<listitem>
<para>
When referring to the <guibutton>OK</guibutton> button, it is not necessary to use "button" in the sentence. For example, "Click <guibutton>OK</guibutton> to close the dialog box."
When referring to the <guibutton>OK</guibutton> button, it is not necessary to use "button" in the sentence.
For example, "Click <guibutton>OK</guibutton> to close the dialog box."
</para>
<para>
Use "OK" only to refer to an interface element, not in general text. For example, instead of using "It is OK to run the command", use alternative wording, such as "You can run the command".
Use "OK" only to refer to an interface element, not in general text.
For example, instead of using "It is OK to run the command", use alternative wording, such as "You can run the command".
</para>
<!-- Added paragraph to avoid "OK" when not referring to a button. -->

</listitem>

Expand All @@ -92,7 +91,8 @@
<term>once</term>
<listitem>
<para>
Use only to mean "one time". Do not use as a conjunction to mean "after" or "when".
Use only to mean "one time".
Do not use as a conjunction to mean "after" or "when".
</para>
<para>
Example 1: Instead of "Once the name is set for a network interface on the system, the name of the interface does not change", use "When the name is set for a network interface on the system, the name of the interface does not change".
Expand Down Expand Up @@ -162,7 +162,9 @@
<term>on-the-fly</term>
<listitem>
<para>
Do not use. Avoid idioms, which might not be globally known. In this case, for example, "real time" is both non-idiomatic and more technically accurate.
Do not use.
Avoid idioms, which might not be globally known.
In this case, for example, "real time" is both non-idiomatic and more technically accurate.
</para>

</listitem>
Expand All @@ -172,7 +174,10 @@
<term>oops</term>
<listitem>
<para>
A kernel oops is an error message that is generated as a result of a bug in the kernel. Do not use "oops" on its own. Also, avoid using "kernel oops" at the beginning of a sentence. See also "kernel panic".
A kernel oops is an error message that is generated because of a bug in the kernel.
Do not use "oops" on its own.
Also, avoid using "kernel oops" at the beginning of a sentence.
See also "kernel panic".
</para>

</listitem>
Expand Down Expand Up @@ -244,10 +249,11 @@
<term>open source way</term>
<listitem>
<para>
A phrase that was coined by the Red&nbsp;Hat community and adopted by opensource.com in 2009. It is a reference to an "open source method", as in "Let's develop this project the open source way."
A phrase that was coined by the Red&nbsp;Hat community and adopted by opensource.com in 2009.
It is a reference to an "open source method", as in "Let's develop this project the open source way."
Copy link
Copy Markdown
Collaborator

@julian-cable julian-cable Feb 3, 2023

Choose a reason for hiding this comment

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

Given our guidance to avoid contractions, we should avoid them here in a quoted example.

</para>
<para>
Do not use to suggest that something is being done only in the "spirit" of open source without actually having an open source policy as defined by <ulink url="http://opensource.org/osd">Open Source Initiative</ulink>, to avoid diluting the legal meaning of the term "open source".
Do not use to suggest that something is being done only in the "spirit" of open source without having an open source policy as defined by <ulink url="http://opensource.org/osd">Open Source Initiative</ulink>, to avoid diluting the legal meaning of the term "open source".
</para>

</listitem>
Expand Down Expand Up @@ -287,7 +293,10 @@
<term>overcloud</term>
<listitem>
<para>
<emphasis>n.</emphasis> Always lowercase. This is a concept, not a technology or product name. Being a common noun, it requires an article in most cases. See also <xref linkend="undercloud" />.
<emphasis>n.</emphasis> Always lowercase.
This is a concept, not a technology or product name.
Being a common noun, it normally requires an article.
See also <xref linkend="undercloud" />.
</para>

</listitem>
Expand All @@ -297,7 +306,8 @@
<term>override</term>
<listitem>
<para>
Correct. Do not use "over-ride" or "over ride".
Correct.
Do not use "over-ride" or "over ride".
</para>

</listitem>
Expand Down
14 changes: 10 additions & 4 deletions en-US/Objectives.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,10 @@
<chapter id="objectives">
<title>Objectives of this Guide</title>
<para>
The objective of the Red&nbsp;Hat Style Guide is to help authors communicate information in a clear, transparent fashion, and to facilitate consistency in tone and delivery. We write documentation for a variety of audiences, across multiple geographies and with very different skill sets. We write for end users as well as expert users. Red&nbsp;Hat documentation is:
The objective of the Red&nbsp;Hat Style Guide is to help authors communicate information in a clear, transparent fashion, and to facilitate consistency in tone and delivery.
We write documentation for various audiences, across multiple geographies and with different skill sets.
We write for end users as well as expert users.
Red&nbsp;Hat documentation is:
<itemizedlist>
<!-- <listitem>
<para>
Expand All @@ -15,13 +18,13 @@

</listitem> --> <listitem>
<para>
Accurate and consistent
Accurate and consistent.
</para>

</listitem>
<listitem>
<para>
Readable, with a score of 60-70 on the Flesch–Kincaid reading ease scale.
Readable, with a score of 60-70 on the Flesch-Kincaid reading ease scale.
</para>

</listitem>
Expand All @@ -44,7 +47,10 @@
<formalpara id="readability">
<title>Readability</title>
<para>
Technical documents should be readable by the targeted audience. In this instance, we expect our audiences to have the minimum reading and comprehension level of an eighth-grade student, of an age between 14 and 15 years. The Flesch-Kincaid and Gunning Fog index provide measurable grades. A Red&nbsp;Hat guide should have a Gunning Fog index of 9-12.
Technical documents should be readable by the targeted audience.
In this instance, we expect our audiences to have the minimum reading and comprehension level of an eighth-grade student, of an age between 14 and 15 years.
The Flesch-Kincaid and Gunning Fog index provide measurable grades.
A Red&nbsp;Hat guide should have a Gunning Fog index of 9-12.
</para>

</formalpara>
Expand Down
22 changes: 13 additions & 9 deletions en-US/P.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,10 +72,13 @@
<term>plain text</term>
<listitem>
<para>
<emphasis>n.</emphasis> Two words. In most cases, do not use "plaintext", "cleartext", or other variants.
<emphasis>n.</emphasis> Two words.
In most cases, do not use "plaintext", "cleartext", or other variants.
</para>
<para>
Cryptographers distinguish between "cleartext" (unencrypted data) and "plaintext" (unencrypted data as input to an encryption algorithm). Red&nbsp;Hat uses "plain text" as a plain English denotation of all unencrypted information, whether it is stored or being fed to an encryption algorithm. Unless it is necessary to make the cryptographer's distinction, do not use "plaintext" or "cleartext".
Cryptographers distinguish between "cleartext" (unencrypted data) and "plaintext" (unencrypted data as input to an encryption algorithm).
Red&nbsp;Hat uses "plain text" as a plain English denotation of all unencrypted information, whether it is stored or being fed to an encryption algorithm.
Unless it is necessary to make the cryptographer's distinction, do not use "plaintext" or "cleartext".
</para>

</listitem>
Expand All @@ -85,9 +88,9 @@
<term>please</term>
<listitem>
<para>
Do not use. Instead of saying "Please see the <citetitle>Getting Started Guide</citetitle>", use "See the <citetitle>Getting Started Guide."</citetitle>
Do not use.
Instead of saying "Please see the <citetitle>Getting Started Guide</citetitle>", use "See the <citetitle>Getting Started Guide."</citetitle>
</para>
<!-- Added justification -->
<para>
Technical information requires an authoritative tone; terms of politeness convey the wrong tone for technical information and are not regarded the same way in all cultures.
</para>
Expand All @@ -109,12 +112,11 @@
<term>plug-in</term>
<listitem>
<para>
<emphasis>n.</emphasis> Write hyphenated. Do not use "plugin".
<emphasis>n.</emphasis> Write hyphenated.
Do not use "plugin".
Copy link
Copy Markdown
Collaborator

@julian-cable julian-cable Feb 3, 2023

Choose a reason for hiding this comment

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

Although some product terminology uses "plugin", and the CCS Supplementary Style Guide now defines the unhyphenated form as the standard.

</para>
<para>
A hardware or software module that adds a specific feature or service to a larger system.
<!-- Removed dated example. -->
<!-- For example, a number of plug-ins are available for the Netscape Navigator browser that enable it to display different types of audio or video messages. Navigator plug-ins are based on MIME file types. -->
</para>

</listitem>
Expand Down Expand Up @@ -173,10 +175,12 @@
<emphasis>n.</emphasis> The name of the Power architecture is "Power", but the designation of individual chips tends to be either "PowerPC" or "POWER". Refer to IBM marketing or the <ulink url="http://openpowerfoundation.org">Open Power Foundation</ulink> if unsure.
</para>
<para>
Do not use the "PPC64" or "ppc64le" shorthand. Depending on context, either "64-bit PowerPC" (which covers most 64-bit PowerPC implementations) or "64-bit IBM Power Series" (which covers the IBM POWER2 and IBM POWER8 and POWER9 series) is correct. Additional application binary interface (ABI) features are important, but are not officially part of the Power architecture name, so use them as descriptors, such as "64-bit IBM Power Series in little-endian mode".
Do not use the "PPC64" or "ppc64le" shorthand.
Depending on context, either "64-bit PowerPC" (which covers most 64-bit PowerPC implementations) or "64-bit IBM Power Series" (which covers the IBM POWER2 and IBM POWER8 and POWER9 series) is correct.
Additional application binary interface (ABI) features are important, but are not officially part of the Power architecture name, so use them as descriptors, such as "64-bit IBM Power Series in little-endian mode".
</para>
<para>
Note: The PowerPC version of Red Hat Enterprise Linux runs on 64-bit IBM Power Series hardware in almost all cases.
Note: The PowerPC version of Red&nbsp;Hat Enterprise Linux runs on 64-bit IBM Power Series hardware in most cases.
</para>

</listitem>
Expand Down
Loading