Skip to content

daobrien/456 vale check #462

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 4 commits into from
Feb 2, 2023
Merged

daobrien/456 vale check #462

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4fc1c91
Merge pull request #447 from StyleGuides/dev
daobrien Dec 13, 2022
1de7eec
Ongoing updates for #456
Feb 1, 2023
70453b7
Closes #456
Feb 2, 2023
1e7ae19
s/may/might/ per Julian's review.
Feb 2, 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
8 changes: 6 additions & 2 deletions en-US/D.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,6 @@
</listitem>

</varlistentry>
<!-- Added "desire". -->
<varlistentry id="desire">
<term>desire</term>
<listitem>
Expand Down Expand Up @@ -210,7 +209,12 @@
<term>digital transformation</term>
<listitem>
<para>
Avoid this phrase. It is vague and could mean use of digital technology to do something faster, to do something differently, or to do a completely new thing. The word "transform" implies a process with a beginning and an end. Some people use the phrase "digital leadership" to describe the ongoing adoption of digital technologies to advance their organization. If you must discuss the concepts of digital transformation or digital leadership, briefly define what you mean on the first occurrence. Describe, rather than label.
Avoid this phrase.
It is vague and could mean use of digital technology to do something faster, to do something differently, or to do something new.
The word "transform" implies a process with a beginning and an end.
Some people use the phrase "digital leadership" to describe the ongoing adoption of digital technologies to advance their organization.
If you must discuss the concepts of digital transformation or digital leadership, briefly define what you mean on the first occurrence.
Describe, rather than label.
</para></listitem>
</varlistentry>
<varlistentry id="disk-druid">
Expand Down
7 changes: 3 additions & 4 deletions en-US/E.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,6 @@
<para>
Refer to the primary reference for the type of copy you are creating, either AP or IBM.
</para>
<!-- Deleted the dated term "e-business". -->

</listitem>

</varlistentry>
Expand All @@ -31,7 +29,8 @@
<term>earlier</term>
<listitem>
<para>
Use to refer to earlier releases of products. Do not use "older" or related terms. See also <xref linkend="later" />.
Use to refer to earlier releases of products. Do not use "older" or related terms.
See also <xref linkend="later" />.
</para>

</listitem>
Expand Down Expand Up @@ -120,7 +119,7 @@
<term>Ethernet</term>
<listitem>
<para>
<emphasis>n.</emphasis> Uppercase "E" at all times.
<emphasis>n.</emphasis> Always capitalize as shown.
</para>

</listitem>
Expand Down
9 changes: 6 additions & 3 deletions en-US/Easily_Confused_Words.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,16 @@
<term>effect</term>
<listitem>
<para>
<emphasis>n.</emphasis> Refers to the result of some action. For example, "the team members discussed the effect of the new policy on their working conditions."
<emphasis>n.</emphasis> Refers to the result of some action.
For example, "the team members discussed the effect of the new policy on their working conditions."
</para>
<para>
<emphasis>v.</emphasis> Means to produce a result, or to cause something to happen. For example, "the CEO claimed that the new policy would effect a positive economic outcome."
<emphasis>v.</emphasis> Means to produce a result, or to cause something to happen.
For example, "the CEO claimed that the new policy would effect a positive economic outcome."
</para>
<para>
The use of "effect" as a verb is less common than the use of "affect", and there are usually alternatives that are clearer. For example, "the CEO claimed that the new policy would produce a positive economic outcome."
The use of "effect" as a verb is less common than the use of "affect", and there are usually alternatives that are clearer.
For example, "the CEO claimed that the new policy would produce a positive economic outcome."
</para>

</listitem>
Expand Down
19 changes: 14 additions & 5 deletions en-US/F.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,15 +252,20 @@
<term>FQDN</term>
<listitem>
<para>
A fully qualified domain name consists of a list of domain labels representing the hierarchy from the lowest relevant level in the DNS to the top-level domain (TLD). The domain labels are concatenated by using the dot or period character (.) as a separator between labels.<footnote><para>https://en.wikipedia.org/wiki/Fully_qualified_domain_name</para></footnote>
A fully qualified domain name consists of a list of domain labels representing the hierarchy from the lowest relevant level in the DNS to the top-level domain (TLD).
The domain labels are concatenated by using the dot or period character (.) as a separator between labels.
<footnote>
<para>
https://en.wikipedia.org/wiki/Fully_qualified_domain_name
</para>
</footnote>
</para>
<para>
For example, <uri>www.redhat.com</uri> is a fully qualified domain name, where <quote>www</quote> is the host, <quote>redhat</quote> is the second-level domain, and <quote>com</quote> is the top-level domain.
For example, <uri>www.redhat.com</uri> is a fully qualified domain name, where "www" is the host, "redhat" is the second-level domain, and "com" is the top-level domain.
</para>
<para>
An FQDN always starts with a hostname and continues all the way up to the top-level domain name; consequently <quote>www.parc.xerox.com</quote> is also an FQDN.
An FQDN always starts with a hostname and continues all the way up to the top-level domain name; consequently "www.parc.xerox.com" is also an FQDN.
</para>
<!-- Changed to "an FQDN". -->

</listitem>

Expand All @@ -269,7 +274,11 @@
<term>frictionless</term>
<listitem>
<para>
Avoid. This term is (a) jargon and (b) inaccurate. Nothing is ever really frictionless. Instead, talk about actual improvement in speed or time. See also <xref linkend="bimodal-it" />.
Avoid.
This term is both jargon and inaccurate.
Nothing is ever really frictionless.
Instead, talk about actual improvement in speed or time.
See also <xref linkend="bimodal-it" />.
</para>

</listitem>
Expand Down
60 changes: 43 additions & 17 deletions en-US/Grammar.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,7 +203,7 @@
<itemizedlist>
<listitem>
<para>
The jewel case, which once held the CD, was broken recently.
The jewel case, which previously held the CD, was broken recently.
</para>

</listitem>
Expand Down Expand Up @@ -299,7 +299,10 @@
<formalpara id="length">
<title>Sentence Length</title>
<para>
Try not to pack too much information into one sentence. In technical documentation, try not to exceed 30 words in a sentence. Keep it short. The following sentence is a bad writing example:
Try not to pack too much information into one sentence.
In technical documentation, try not to exceed 30 words in a sentence.
Keep it short.
The following sentence is a bad writing example:
</para>

</formalpara>
Expand Down Expand Up @@ -328,13 +331,15 @@
<itemizedlist>
<listitem>
<para>
Separate independent clauses with a period. Doing so will form two sentences out of one.
Separate independent clauses with a period.
This creates two sentences from one.
</para>

</listitem>
<listitem>
<para>
Use semicolons to form a compound sentence. Think of a semicolon as an extended breather; it is longer than a comma.
Use semicolons to form a compound sentence.
Think of a semicolon as an extended breather; it is longer than a comma.
</para>

</listitem>
Expand Down Expand Up @@ -390,13 +395,17 @@
<formalpara id="fragments">
<title>Sentence Fragments</title>
<para>
A <firstterm>sentence fragment</firstterm> is an incomplete sentence. For example, "Red Hat releases no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade. At least, before its time." the second of the two sentences is a fragment. Repair sentence fragments by making them complete sentences.
A <firstterm>sentence fragment</firstterm> is an incomplete sentence.
For example, "Red&nbsp;Hat releases no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade.
At least, before its time." the second of the two sentences is a fragment.
Repair sentence fragments by making them complete sentences.
</para>

</formalpara>
<note>
<para>
Read your sentences aloud, as if each sentence were the *only* sentence on a piece of paper. If you hear a sentence that does not make any sense by itself, then it is probably a sentence fragment.
Read your sentences aloud, as if each sentence were the *only* sentence on paper.
If you hear a sentence that does not make any sense by itself, then it is probably a sentence fragment.
</para>

</note>
Expand All @@ -423,7 +432,7 @@
<tbody>
<row>
<entry> Click button to start. </entry>
<entry> Click <guibutton>Initiate</guibutton> to start the process. </entry>
<entry> Click <guibutton>Start</guibutton> to start the process. </entry>

</row>

Expand Down Expand Up @@ -717,8 +726,8 @@

</row>
<row>
<entry> A site can use these to self-allocate a private routable IP address space inside the organization. </entry>
<entry> A site can use these unique local addresses to self-allocate a private routable IP address space inside the organization. </entry>
<entry> A site can use these to self-assign a private routable IP address space inside the organization. </entry>
<entry> A site can use these unique local addresses to self-assign a private routable IP address space inside the organization. </entry>

</row>

Expand Down Expand Up @@ -773,7 +782,8 @@
<formalpara id="word-order">
<title>Word Order</title>
<para>
When two or more correct arrangements are possible, choose the order that will create the least ambiguity. Generally, this is the standard subject-verb-object, with modifiers before or immediately following what they modify.
When two or more correct arrangements are possible, choose the order that creates the least ambiguity.
Generally, this is the standard subject-verb-object sequence, with modifiers before or immediately following what they modify.
</para>

</formalpara>
Expand Down Expand Up @@ -814,7 +824,11 @@ Split contractions and abbreviations into separate paragraphs. -->
<section id="contractions-and-abbreviations">
<title>Contractions and Abbreviations</title>
<para>
Do not use contractions in Red&nbsp;Hat documents. For example, do not use "can't", "don't", "won't", and similar examples. Write out the words in full. Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. They can also cause problems for translation.
Do not use contractions in Red&nbsp;Hat documents.
For example, do not use can't, "don't", "won't", and similar examples.
Write out the words in full.
Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals.
They can also cause problems for translation.
</para>

<para>
Expand All @@ -826,7 +840,10 @@ Split contractions and abbreviations into separate paragraphs. -->
<section id="hyphenation">
<title>Hyphenation</title>
<para>
There are no hard and fast rules for hyphenation. In general, do not hyphenate unless required for clarity, or our other references declare that hyphens are required. The following is general guidance; if you are unsure about whether or not to hyphenate, ask your peers. See also the "Hyphens" topic in the <citetitle>IBM Style Guide</citetitle>.
No hard and fast rules exist for hyphenation.
In general, do not hyphenate unless required for clarity, or your other references declare that hyphens are required.
The following is general guidance; if you are unsure about whether to hyphenate, ask your peers.
See also the "Hyphens" topic in the <citetitle>IBM Style Guide</citetitle>.
</para>

<formalpara id="hyphenate-for-clarity">
Expand Down Expand Up @@ -893,13 +910,19 @@ Split contractions and abbreviations into separate paragraphs. -->
<section id="pronouns-gender-references">
<title>Pronouns and Gender References</title>
<para>
Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is easier to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers". It is acceptable to use "they" to refer to one person, with a plural verb.
Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study.
It is easier to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers".
It is acceptable to use "they" to refer to one person, with a plural verb.
</para>
<para>
In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "users" or "new users". Do not use "one" in place of "you" when writing technical documentation, because it is too formal. Do not use "it" to refer to a person.
Usually, when giving instructions, use the imperative mood or use "you".
In more general explanations, you can use "users" or "new users".
Do not use "one" in place of "you" when writing technical documentation, because it is too formal.
Do not use "it" to refer to a person.
</para>
<para>
Avoid first person "I, we, our". Use second person "you" whenever possible.
Avoid first person "I, we, our".
Use second person "you" whenever possible.
</para>
<para>
If referring to what Red&nbsp;Hat does, use "Red&nbsp;Hat" followed by a singular verb.
Expand Down Expand Up @@ -945,11 +968,14 @@ Split contractions and abbreviations into separate paragraphs. -->
<section id="tense">
<title>Tense</title>
<para>
Avoid future tense (or using the term "will") whenever possible. For example, future tense ("The window will open ...") does not read as well as the present tense ("The window opens ..."). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system.
Avoid future tense (or using the term "will") whenever possible.
For example, future tense ("The window will open ...") does not read as well as the present tense ("The window opens ...").
Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system.
</para>

<para>
Use simple present tense as much as possible. It avoids problems with consequences and time-related communications, and is the easiest tense for translation.
Use simple present tense as much as possible.
It avoids problems with consequences and time-related communications, and is the easiest tense for translation.
</para>
<para>
<ulink url="https://github.com/StyleGuides/WritingStyleGuide/issues">Report an issue</ulink>
Expand Down
40 changes: 14 additions & 26 deletions en-US/H.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,41 +57,26 @@
<term>he/she</term>
<listitem>
<para>
Do not use. Reword to avoid. In most cases, "they" is acceptable as a singular pronoun.
Do not use.
Usually, "they" is acceptable as a singular pronoun.
</para>

</listitem>

</varlistentry>
<!-- <varlistentry id="healthcare">
<term>healthcare</term>
<listitem>
<para>
<remark>Under review. Need context and example.</remark>

</para>

</listitem>

</varlistentry> -->
<varlistentry id="health-check">
<term>health check</term>
<listitem>
<para>
<emphasis>n.</emphasis> Two words. This is a change from the previous style standard (one word) to take advantage of the better search ranking of the two-word variation, and is used in product names that are similar to competitive offerings in the same space.
<emphasis>n.</emphasis> Two words.
This is a change from the previous style standard (one word) to take advantage of the better search ranking of the two-word variation, and is used in product names that are similar to competitive offerings in the same space.
</para>
<para>
This term is only capitalized when part of a product name, for example:
<itemizedlist>
<listitem>
<para>
<productname>Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;Server Health&nbsp;Check</productname>
</para>

</listitem>
<listitem>
<para>
<productname>JBoss Middleware&nbsp;Health&nbsp;Check</productname>
<productname>Red&nbsp;Hat Enterprise Linux Server Health Check</productname>
</para>

</listitem>
Expand All @@ -100,7 +85,8 @@

</para>
<para>
Do not capitalize when referring to those services in a general way. For example: "A health check ensures that your systems perform at their best."
Do not capitalize when referring to those services in a general way.
For example: "A health check ensures that your systems perform at their best."
</para>

</listitem>
Expand Down Expand Up @@ -131,12 +117,13 @@
<term>high-availability, high availability</term>
<listitem>
<para>
<emphasis>adj.</emphasis> Hyphenate, except as part of a product name. For example, "high-availability cluster".
<!-- Do not use "high availability". -->
<emphasis>adj.</emphasis> Hyphenate, except as part of a product name.
For example, "high-availability cluster".
</para>

<para>
<emphasis>n.</emphasis> Two words. For example, "Support is available 24x7 to help maintain high availability."
<emphasis>n.</emphasis> Two words.
For example, "Support is available 24x7 to help maintain high availability."
</para>

</listitem>
Expand All @@ -156,7 +143,8 @@
<term>home page</term>
<listitem>
<para>
<emphasis>n.</emphasis> Two words. Capitalize the "H" at the beginning of a sentence. If part of a proper noun, capitalize accordingly.
<emphasis>n.</emphasis> Two words.
Capitalize the "H" at the beginning of a sentence or if part of a proper noun.
</para>

</listitem>
Expand All @@ -176,7 +164,7 @@
<term>hostname</term>
<listitem>
<para>
<emphasis>n.</emphasis> One word in most cases.
<emphasis>n.</emphasis> Usually one word.
Capitalize the "H" at the beginning of a sentence.
See the <citetitle>IBM Style Guide</citetitle> for more information.
</para>
Expand Down
Loading