From ce9dd60254d06ac11fa3ffc9ad1fb55e16c8d308 Mon Sep 17 00:00:00 2001 From: daobrien Date: Tue, 20 Dec 2022 00:22:35 +1000 Subject: [PATCH 01/79] Working on #450. --- en-US/A.xml | 18 ++++++++---------- en-US/Author_Group.xml | 2 +- en-US/B.xml | 5 ++--- en-US/Book_Design.xml | 6 ++++-- en-US/Cross_references.xml | 2 +- 5 files changed, 16 insertions(+), 17 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index 48c5460..52368b4 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -5,9 +5,7 @@ ]> A - - "&" and "+" @@ -55,10 +53,10 @@ all-in-one - allinone - n., adj. Hyphenate in both places. Do not use "allinone" or other variations. + n., adj. Write as shown as both a noun and an adjective. + Do not use other variations. @@ -78,7 +76,7 @@ - + alternative @@ -98,7 +96,7 @@ For times of day, use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". - + See also . @@ -123,7 +121,7 @@ The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . - + For more information about Intel® trademarks, see and . @@ -157,9 +155,9 @@ - + - + diff --git a/en-US/Author_Group.xml b/en-US/Author_Group.xml index ab048b7..0c30a92 100644 --- a/en-US/Author_Group.xml +++ b/en-US/Author_Group.xml @@ -5,7 +5,7 @@ ]> - Red Hat Documentation Team + Red Hat Documentation Team diff --git a/en-US/B.xml b/en-US/B.xml index ebfca95..31cf889 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -75,7 +75,6 @@ Do not use. Instead, use "compatible with earlier versions" to refer to something that is compatible with older equipment or previous versions of software. See also . - @@ -362,8 +361,8 @@ broadcast - To send the same message simultaneously to multiple recipients. Broadcasting is a useful feature in email systems. - diff --git a/en-US/Book_Design.xml b/en-US/Book_Design.xml index 636518f..ca49a26 100644 --- a/en-US/Book_Design.xml +++ b/en-US/Book_Design.xml @@ -99,7 +99,9 @@ Drawing these basics together might produce the following example abstract: - "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API. The guide explains each API method and demonstrates examples of data models for input and output. This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." + "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API. + The guide explains each API method and demonstrates examples of data models for input and output. + This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." Update or modify each component according to the type of book that you are writing. @@ -122,7 +124,7 @@
Unused Heading Titles - + This section lists various heading titles that might be used in Red Hat technical documentation, but that should be avoided except in specific circumstances. diff --git a/en-US/Cross_references.xml b/en-US/Cross_references.xml index 546c632..5468451 100644 --- a/en-US/Cross_references.xml +++ b/en-US/Cross_references.xml @@ -45,7 +45,7 @@ Must the information be repeated? - This is a hard question, and one that many authors abhor. Often the answer is yes. If the information is vital, and must appear in multiple places, then it must be repeated. It's not a crime. In some circumstances, such is in online help, the reader wants the answer immediately. Do not force even one extra click on them. In a safety situation, it might be the only chance for the reader to find critical information quickly. Any vital information, which is not more than a couple of paragraphs (or half a page, or five rows of a table), can be repeated rather than be cross-referenced to. + This is a hard question, and one that many authors abhor. Often the answer is yes. If the information is vital, and must appear in multiple places, then it must be repeated. In some circumstances, such is in online help, the reader wants the answer immediately. Do not force even one extra click on them. In a safety situation, it might be the only chance for the reader to find critical information quickly. Any vital information, which is not more than a couple of paragraphs (or half a page, or five rows of a table), can be repeated rather than be cross-referenced to. Cross-referencing is a good servant but a poor master. Content still rules! From c00a40efff510df53ee33021023ed301b29422b7 Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 23 Jan 2023 17:08:45 +1000 Subject: [PATCH 02/79] Run Vale over Design.xml. This is the end of part 1/4 of "Run Vale over the style guide." Too big a job to try to handle in one issue and PR. --- en-US/Design.xml | 63 +++++++++++++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 25 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 297d79f..7bb1591 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -16,7 +16,7 @@ Capitalization The standard for all Red Hat technical documentation is title case for all headings and titles. - Table headings, procedure headings, and formal paragraph titles fall under this heading, and consequently, standard title case capitalization rules apply. + Table headings, procedure headings, and formal paragraph titles fall under this heading; standard title case capitalization rules apply. @@ -42,7 +42,7 @@ Be frugal with punctuation. - In most cases, avoid semicolons, colons, dashes, and similar punctuation unless part of the actual subject, or a proper name. + Avoid semicolons, colons, dashes, and similar punctuation unless part of the actual subject, or a proper name. Do not use terminating periods. @@ -102,7 +102,7 @@ For example, for a button labeled Save As..., do not include the ellipsis in the documentation. - In most cases, do not include the element type in instructions. + Avoid including the element type in instructions. For example, rather than "Click the Save button", write "Click Save". @@ -136,7 +136,7 @@
Navigating Through Multiple UI Options - Use "Navigate to" when moving through multiple UI options because it covers all cases where you might have to click, point to, press, select, or otherwise make a series of selections to initiate an action. + Use "Navigate to" when moving through multiple UI options because it covers all cases where you might have to click, point to, press, select, or otherwise make a series of selections to start an action. For example, "From the OpenShift web console, navigate to Monitoring → Alerting." @@ -182,7 +182,7 @@ RHEL 8 uses the following approach to starting applications from the desktop. - In an effort to maintain consistency and to make translation easier, Red Hat documentation assumes use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. + To maintain consistency and to make translation easier, Red Hat documentation assumes the use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. The preferred approach is to use the Super key to enter the Activities Overview, to enter the name of the required application, and to press Enter. @@ -272,7 +272,7 @@ Target options [directory] - The optional directory into which the repository will be cloned. + The optional directory into which the repository is cloned. It must be replaced with a valid value, or be omitted. @@ -326,7 +326,8 @@ Target options ([username@]hostname:/directory) - The optional username, indicated by brackets ([]), followed by the hostname and path to the target directory. All aspects of this component must be replaced with valid values. + The optional username, indicated by brackets, [], followed by the hostname and path to the target directory. + All aspects of this component must be replaced with valid values. @@ -336,7 +337,7 @@ - In most cases, avoid using the and options on most commands, especially when logged in as the root user. This can lead to unintended consequences, such as removing files or directories by mistake or installing packages or other software that might not suit your system. Refer to the following examples: + Avoid using the and options on most commands, especially when logged in as the root user. This can lead to unintended consequences, such as removing files or directories by mistake or installing packages or other software that might not suit your system. Refer to the following examples: [root@serverc pam.d]# rm -f system-auth password-auth @@ -353,7 +354,8 @@
Documenting Multiple or Long Commands - Sometimes you need to demonstrate how to use long commands that extend over two or more lines, or that include several commands in a single example. If the commands are relatively short and straightforward, then include the commands on consecutive lines: + Sometimes you need to show how to use long commands that extend over two or more lines, or that include several commands in a single example. + If the commands are relatively short and straightforward, then include the commands on consecutive lines. Documenting Multiple Commands @@ -387,7 +389,7 @@ $ vi myFile.txt Do not mix these styles. - Maintain the same style throughout your document, book, and product set. + Use the same style throughout your document, book, and product set. @@ -410,7 +412,7 @@ $ vi myFile.txt Wrapping Long Commands Without Continuation Characters or PS2 Prompts - This example uses neither continuation characters nor PS2 prompts, but it does demonstrate how to use line indentation to help to clarify long commands. + This example uses neither continuation characters nor PS2 prompts, but it does show how to use line indentation to help to clarify long commands. # cd /var/lib/katello @@ -470,7 +472,7 @@ $ vi myFile.txt The term escalated privileges refers to changing to a user whose privileges allow operations that a normal user cannot access. - It also refers to temporarily changing the privileges of the current user to perfom those operations without actually changing user accounts. + It also refers to temporarily changing the privileges of the current user to perfom those operations without changing user accounts. @@ -587,7 +589,8 @@ $ vi myFile.txt
Using Host and Usernames Correctly - Many examples in Red Hat documentation require the use of usernames, hostnames, IP addresses, and similar information. In an effort to reduce security risks, to minimize translation overhead, and to maintain consistency, Red Hat recommends the following approach. + Many examples in Red Hat documentation require the use of usernames, hostnames, IP addresses, and similar information. + To reduce security risks, to minimize translation overhead, and to maintain consistency, Red Hat recommends the following approach: @@ -598,7 +601,8 @@ $ vi myFile.txt - Use RFC 2606 to determine suitable domain names. For documentation and example purposes, it is typically example.com, example.net, example.org, and example.edu. + Use RFC 2606 to find suitable domain names. + For documentation and example purposes, it is typically example.com, example.net, example.org, and example.edu. @@ -618,7 +622,7 @@ $ vi myFile.txt [root@fedora ~]# setfacl -m u:user1:rw /project/file1 - The following list provides further alternatives: + The following list provides further options: @@ -685,7 +689,8 @@ $ vi myFile.txt - Include a diverse set of names in your examples to reflect the diversity of the real world. For example, use male, female, and culturally diverse names that suggest a variety of backgrounds in examples to avoid implying that only certain groups have specific skills. + Include a diverse set of names in your examples to reflect the diversity of the real world. + For example, use male, female, and culturally diverse names that suggest various backgrounds in examples to avoid implying that only certain groups have specific skills. @@ -1087,14 +1092,18 @@ $ vi myFile.txt - In most cases, major changes take place in major version releases, and are carried through any minor updates to that release. If you are referring to a major change, or to the first appearance of a new technology, it is therefore most accurate to refer to the major release. + Major changes usually take place in major version releases, and are carried through any minor updates to that release. + If you are referring to a major change, or to the first appearance of a new technology, it is therefore most accurate to refer to the major release. - Avoid using the "dot-oh" release number. For example, do not use Red Hat Enterprise Linux 6.0. Use instead Red Hat Enterprise Linux 6. + Avoid using the "dot-oh" release number. + For example, do not use Red Hat Enterprise Linux 6.0. + Use instead Red Hat Enterprise Linux 6. - This rule applies only to Red Hat products. Refer to other companies' products and use their version numbers as they use them. + This rule applies only to Red Hat products. + Refer to other companies' products and use their version numbers as they use them. @@ -1103,14 +1112,17 @@ $ vi myFile.txt
Using Admonitions - To call attention to a statement, use an admonition. Red Hat technical documentation currently uses Note, Important, and Warning admonitions. + To call attention to a statement, use an admonition. + Red Hat technical documentation currently uses Note, Important, and Warning admonitions. - Admonitions automatically include a suitable title according to the type of admonition. Do not use a phrase or anything else for the title. Keep in mind these considerations if using admonitions: + Admonitions automatically include a suitable title according to the type of admonition. + Do not use a phrase or anything else for the title. + Keep the following considerations in mind if using admonitions: - Keep the statements as brief and to the point as possible. + Keep statements brief and to the point. @@ -1122,19 +1134,20 @@ $ vi myFile.txt - Use a Note admonition to bring additional information to the user's attention. + Use a Note admonition to bring extra information to the user's attention. - Use an Important admonition to show the user a piece of information that should not be overlooked. While this information might not change anything that the user is doing, it should show the user that this piece of information could be vital. + Use an Important admonition to show the user a piece of information that should not be overlooked. + This information might not change anything that the user is doing, but it should show the user that this piece of information could be vital. - Use a Warning admonition to alert the reader that the current setup will change or be altered, such as files being removed, and not to perform the operation unless fully aware of the consequences. + Use a Warning admonition to alert the reader to potential changes, such as files being removed, and not to perform the operation unless fully aware of the consequences. From 1de7eecf9379e1a24716f1a00ae270a6f1a60ad1 Mon Sep 17 00:00:00 2001 From: daobrien Date: Thu, 2 Feb 2023 00:15:33 +1000 Subject: [PATCH 03/79] Ongoing updates for #456 --- en-US/D.xml | 8 +++-- en-US/E.xml | 7 ++-- en-US/Easily_Confused_Words.xml | 9 +++-- en-US/F.xml | 19 ++++++++--- en-US/Grammar.xml | 60 +++++++++++++++++++++++---------- en-US/H.xml | 40 ++++++++-------------- 6 files changed, 86 insertions(+), 57 deletions(-) diff --git a/en-US/D.xml b/en-US/D.xml index e927504..8e8f0b3 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -142,7 +142,6 @@ - desire @@ -210,7 +209,12 @@ digital transformation - 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. diff --git a/en-US/E.xml b/en-US/E.xml index b76ba72..343e765 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -12,8 +12,6 @@ Refer to the primary reference for the type of copy you are creating, either AP or IBM. - - @@ -31,7 +29,8 @@ earlier - Use to refer to earlier releases of products. Do not use "older" or related terms. See also . + Use to refer to earlier releases of products. Do not use "older" or related terms. + See also . @@ -120,7 +119,7 @@ Ethernet - n. Uppercase "E" at all times. + n. Always capitalize as shown. diff --git a/en-US/Easily_Confused_Words.xml b/en-US/Easily_Confused_Words.xml index ef02831..4c464ff 100644 --- a/en-US/Easily_Confused_Words.xml +++ b/en-US/Easily_Confused_Words.xml @@ -33,13 +33,16 @@ effect - n. Refers to the result of some action. For example, "the team members discussed the effect of the new policy on their working conditions." + n. Refers to the result of some action. + For example, "the team members discussed the effect of the new policy on their working conditions." - v. 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." + v. 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." - 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." diff --git a/en-US/F.xml b/en-US/F.xml index 9636404..81324ec 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -252,15 +252,20 @@ FQDN - 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.https://en.wikipedia.org/wiki/Fully_qualified_domain_name + 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. + + + https://en.wikipedia.org/wiki/Fully_qualified_domain_name + + - For example, www.redhat.com is a fully qualified domain name, where www is the host, redhat is the second-level domain, and com is the top-level domain. + For example, www.redhat.com is a fully qualified domain name, where "www" is the host, "redhat" is the second-level domain, and "com" is the top-level domain. - 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. + 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. - @@ -269,7 +274,11 @@ frictionless - 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 . + Avoid. + This term is both jargon and inaccurate. + Nothing is ever really frictionless. + Instead, talk about actual improvement in speed or time. + See also . diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 2eb37eb..4457d31 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -203,7 +203,7 @@ - The jewel case, which once held the CD, was broken recently. + The jewel case, which previously held the CD, was broken recently. @@ -299,7 +299,10 @@ Sentence Length - 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: @@ -328,13 +331,15 @@ - 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. - 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. @@ -390,13 +395,17 @@ Sentence Fragments - A sentence fragment 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 sentence fragment 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. - 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. @@ -423,7 +432,7 @@ Click button to start. - Click Initiate to start the process. + Click Start to start the process. @@ -717,8 +726,8 @@ - A site can use these to self-allocate a private routable IP address space inside the organization. - A site can use these unique local addresses to self-allocate a private routable IP address space inside the organization. + A site can use these to self-assign a private routable IP address space inside the organization. + A site can use these unique local addresses to self-assign a private routable IP address space inside the organization. @@ -773,7 +782,8 @@ Word Order - 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. @@ -814,7 +824,11 @@ Split contractions and abbreviations into separate paragraphs. -->
Contractions and Abbreviations - Do not use contractions in Red 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 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. @@ -826,7 +840,10 @@ Split contractions and abbreviations into separate paragraphs. -->
Hyphenation - 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 IBM Style Guide. + 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 IBM Style Guide. @@ -893,13 +910,19 @@ Split contractions and abbreviations into separate paragraphs. -->
Pronouns and Gender References - 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. - 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. - Avoid first person "I, we, our". Use second person "you" whenever possible. + Avoid first person "I, we, our". + Use second person "you" whenever possible. If referring to what Red Hat does, use "Red Hat" followed by a singular verb. @@ -945,11 +968,14 @@ Split contractions and abbreviations into separate paragraphs. -->
Tense - 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. - 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. Report an issue diff --git a/en-US/H.xml b/en-US/H.xml index dea3153..5f87a4c 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -57,41 +57,26 @@ he/she - 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. - health check - n. 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. + n. 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. This term is only capitalized when part of a product name, for example: - Red Hat Enterprise Linux Server Health Check - - - - - - JBoss Middleware Health Check + Red Hat Enterprise Linux Server Health Check @@ -100,7 +85,8 @@ - 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." @@ -131,12 +117,13 @@ high-availability, high availability - adj. Hyphenate, except as part of a product name. For example, "high-availability cluster". - + adj. Hyphenate, except as part of a product name. + For example, "high-availability cluster". - n. Two words. For example, "Support is available 24x7 to help maintain high availability." + n. Two words. + For example, "Support is available 24x7 to help maintain high availability." @@ -156,7 +143,8 @@ home page - n. Two words. Capitalize the "H" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. + n. Two words. + Capitalize the "H" at the beginning of a sentence or if part of a proper noun. @@ -176,7 +164,7 @@ hostname - n. One word in most cases. + n. Usually one word. Capitalize the "H" at the beginning of a sentence. See the IBM Style Guide for more information. From 70453b700532987e2c985a4c80222f888967990b Mon Sep 17 00:00:00 2001 From: daobrien Date: Thu, 2 Feb 2023 18:27:58 +1000 Subject: [PATCH 04/79] Closes #456 Part 2 of running Vale over the style guide. I also addressed a few other issues along the way, such as one sentence per line and removing old comments. Language.xml in particular contains lots of examples of what not to do, so it produces lots of noise in Vale. --- en-US/I.xml | 116 +++++++++++++++++++++++------------------- en-US/K.xml | 13 +++-- en-US/L.xml | 12 +++-- en-US/Language.xml | 123 +++++++++++++++++++++++++++++++-------------- 4 files changed, 167 insertions(+), 97 deletions(-) diff --git a/en-US/I.xml b/en-US/I.xml index 1408dac..541daeb 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -36,28 +36,16 @@ - IBM Z - IBM Z is a family name used by IBM for all of its mainframe computers from the Z900 on. In 2017, the official family was changed to IBM Z from IBM z Systems. + IBM Z is a family name used by IBM for all its mainframe computers from the Z900 on. + In 2017, the official family was changed to IBM Z from IBM z Systems. - i.e. @@ -80,12 +68,13 @@ - indexes - Correct. This is the correct plural form for US English spelling. Do not use "indices". + Correct. + This is the correct plural form for US English spelling. + Do not use "indices". @@ -96,7 +85,10 @@ InfiniBand - InfiniBand is a switched fabric network topology that is used in high-performance computing. The term is both a service mark and a trademark of the InfiniBand Trade Association. Their rules for using the mark are standard ones: append the ™ symbol the first time that it is used and respect the capitalization (including the inter-capped "B") from then on. In ASCII-only circumstances, the "(TM)" string is the acceptable alternative. + InfiniBand is a switched fabric network topology that is used in high-performance computing. + The term is both a service mark and a trademark of the InfiniBand Trade Association. + Their rules for using the mark are standard ones: append the ™ symbol the first time that it is used and respect the capitalization (including the inter-capped "B") from then on. + In ASCII-only circumstances, the "(TM)" string is the acceptable alternative. "Open InfiniBand" is deprecated and should not be used. @@ -109,7 +101,8 @@ inline - adj. Always one word. Do not hyphenate. + adj. Always one word. + Do not hyphenate. @@ -119,7 +112,8 @@ insecure - adj. Correct. Do not use "nonsecure" or "non-secure". + adj. Correct. + Do not use "nonsecure" or "non-secure". @@ -129,7 +123,8 @@ installation program - n. Correct. Do not use "installer" unless it is a formal part of the product or technology. + n. Correct. + Do not use "installer" unless it is a formal part of the product or technology. @@ -139,12 +134,12 @@ Intel 64 - Correct. Do not use "Hammer", "x86_64", "x86-64", "x64", "64-bit x86", or other variations as the name of this architecture. + Correct. + Do not use "Hammer", "x86_64", "x86-64", "x64", "64-bit x86", or other variations as the name of this architecture. The correct term for Intel's implementation of this architecture is "Intel® 64". - - When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. + When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. See also . @@ -179,7 +174,8 @@ Intel Tolapai / Intel® EP80579 Integrated Processor - Do not use the code-name, "Tolapai". Use the official brand name "Intel® EP80579 Integrated Processor". + Do not use the code-name, "Tolapai". + Use the official brand name "Intel® EP80579 Integrated Processor". @@ -189,10 +185,15 @@ Intel Virtualization Technology (Intel VT) - Correct. The first and all prominent uses of the name should be fully spelled out, immediately followed by the initialism. For example, "Intel Virtualization Technology (Intel VT) for Intel 64 or Itanium architecture (Intel Vi). Subsequent uses can be abbreviated to "Intel Vi". + Correct. + The first and all prominent uses of the name should be fully spelled out, immediately followed by the initialism. + For example, "Intel Virtualization Technology (Intel VT) for Intel 64 or Itanium architecture (Intel Vi). + Subsequent uses can be abbreviated to "Intel Vi". - Always write the initialism in uppercase, accompanied by the "Intel" mark. Do not use "Vi" or "VT". Do not use the initialism in any prominent places, such as in titles or paragraph headings, and do not include any trademark symbols, such as ™ or "(TM)". + Always write the initialism in uppercase, accompanied by the "Intel" mark. + Do not use "Vi" or "VT". + Do not use the initialism in any prominent places, such as in titles or paragraph headings, and do not include any trademark symbols, such as ™ or "(TM)". @@ -213,7 +214,8 @@ interesting - Avoid this term, because it is a substitute for showing the reader why something is of interest. For example, instead of writing "It is interesting to note ...", consider using a "Note" admonition. + Avoid this term, because it is a substitute for showing the reader why something is of interest. + For example, instead of writing "It is interesting to note ...", consider using a "Note" admonition. @@ -233,7 +235,8 @@ Internet of Things (IoT) - Correct. Capitalize as shown; spell out on the first occurrence; and use the initialism thereafter. + Correct. + Capitalize as shown; spell out on the first occurrence, and use the initialism thereafter. The Internet of Things (IoT) refers to uniquely identifiable objects and their virtual representations in an internet-like structure. @@ -259,10 +262,17 @@ I/O - Correct. Stands for input/output (pronounced "eye-oh"). The term "I/O" is used to describe any program, operation, or device that transfers data to or from a computer and to or from a peripheral device. Every transfer is an output from one device and an input into another. Devices such as keyboards and mice are input-only devices, while devices such as printers are output-only. A writable CD is both an input and an output device. + Correct. + Stands for input/output (pronounced "eye-oh"). + The term "I/O" is used to describe any program, operation, or device that transfers data to or from a computer and to or from a peripheral device. + Every transfer is an output from one device and an input into another. + Devices such as keyboards and mice are input-only devices; devices such as printers are output-only. + A writable CD is both an input and an output device. - The term "I/O" is a non-countable noun. Append "operations" to refer to multiple units of I/O. For example: I/O operations could not be recovered in situations where I/O should have been temporarily queued, such as when paths were unavailable. + The term "I/O" is a non-countable noun. + Append "operations" to refer to multiple units of I/O. + For example: I/O operations could not be recovered in situations where I/O should have been temporarily queued, such as when paths were unavailable. @@ -272,7 +282,9 @@ IOPS - Correct. All caps. Stands for input/output operations per second. + Correct. + All caps. + Stands for input/output operations per second. @@ -282,7 +294,9 @@ IP - Correct. Stands for Internet Protocol. Capitalize both letters. + Correct. + Stands for Internet Protocol. + Capitalize both letters. @@ -292,7 +306,9 @@ IP Masquerade - A Linux networking function. IP Masquerade, also called IPMASQ or MASQ, allows one or more computers in a network without assigned IP addresses to communicate with the internet by using the Linux server's assigned IP address. The IPMASQ server acts as a gateway, and the other devices are invisible behind it, so to other machines on the internet the outgoing traffic appears to be coming from the IPMASQ server and not from the internal PCs. + A Linux networking function. + IP Masquerade, also called IPMASQ or MASQ, allows one or more computers in a network without assigned IP addresses to communicate with the internet by using the Linux server's assigned IP address. + The IPMASQ server acts as a gateway, and the other devices are invisible behind it, so to other machines on the internet the outgoing traffic appears to be coming from the IPMASQ server and not from the internal PCs. Because IPMASQ is a generic technology, the server can be connected to other computers through LAN technologies such as Ethernet, Token-Ring, and FDDI, as well as dial-up connections such as PPP or SLIP. @@ -305,7 +321,9 @@ IPsec - IPsec stands for Internet Protocol security. According to its RFC, IPsec should be used. Do not use "IPSec". + IPsec stands for Internet Protocol security. + According to its RFC, IPsec should be used. + Do not use "IPSec". @@ -315,7 +333,9 @@ IP switching - A type of IP routing that Ipsilon Networks, Inc. developed. Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. This type of IP routing appears to be considerably faster than older router techniques. + A type of IP routing that Ipsilon Networks, Inc. developed. + Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. + This type of IP routing appears to be considerably faster than previous router techniques. @@ -345,16 +365,20 @@ Itanium - A member of Intel's Merced family of processors, Itanium is a 64-bit RISC microprocessor. Based on the EPIC (Explicitly Parallel Instruction Computing) design philosophy, which states that the compiler should decide which instructions should be executed together, Itanium has the highest FPU power available. + A member of Intel's Merced family of processors, Itanium is a 64-bit RISC microprocessor. + Based on the EPIC (Explicitly Parallel Instruction Computing) design philosophy, which states that the compiler should decide which instructions should be executed together, Itanium has the highest FPU power available. - In 64-bit mode, Itanium can calculate two bundles of a maximum of three instructions at a time. In 32-bit mode, it is much slower. Decoders must first translate 32-bit instruction sets into 64-bit instruction sets, which results in extra-clock cycle use. + In 64-bit mode, Itanium can calculate two bundles of a maximum of three instructions at a time. + In 32-bit mode, it is much slower. + Decoders must first translate 32-bit instruction sets into 64-bit instruction sets, which results in extra-clock cycle use. Itanium's primary use is driving large applications that require more than 4 GB of memory, such as databases, ERP, and future internet applications. - Do not use the term "IA64". It can be used in file names because they are not printed in the content. + Do not use the term "IA64". + It can be used in file names because they are not printed in the content. @@ -364,26 +388,14 @@ Itanium 2 - Itanium 2 is correct. Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2". - - - - - - - diff --git a/en-US/K.xml b/en-US/K.xml index dcad72e..b6d9127 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -43,7 +43,10 @@ kernel - The central module of an operating system. It is the part of the operating system that loads first, and it remains in main memory. Because it stays in memory, it is important for the kernel to be as small as possible while still providing all the essential services that other parts of the operating system and applications require. Typically, the kernel is responsible for memory management, process and task management, and disk management. + The central module of an operating system. + It is the part of the operating system that loads first, and it remains in main memory. + Because it stays in memory, it is important for the kernel to be as small as possible but still provide all the essential services that other parts of the operating system and applications require. + Typically, the kernel is responsible for memory management, process and task management, and disk management. @@ -63,7 +66,8 @@ kernel panic - Correct. Numerous circumstances might cause a kernel panic, but unlike a kernel oops, when confronted with a kernel panic the operating system shuts down to prevent the possibility of further damage or security breaches. + Correct. + Many different circumstances might cause a kernel panic, but unlike a kernel oops, when confronted with a kernel panic the operating system shuts down to prevent the possibility of further damage or security breaches. @@ -148,7 +152,10 @@ kill - If terminating a UNIX process, use "kill". For example, to terminate the process, type kill <PID>. If terminating a Windows process, use "terminate". For example, "To terminate the process, press Q." + If terminating a UNIX process, use "kill". + For example, to terminate the process, type kill <PID>. + If terminating a Windows process, use "terminate". + For example, "To terminate the process, press Q." diff --git a/en-US/L.xml b/en-US/L.xml index 07c969b..b37b011 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -160,7 +160,11 @@ load balancing - Distributing processing and communications activity evenly across a computer network so that no single device is overwhelmed. Load balancing is especially important for networks where it is difficult to predict the number of requests that are issued to a server. Busy websites typically employ two or more web servers in a load balancing scheme. If one server starts to get swamped, requests are forwarded to another server with more capacity. Load balancing can also refer to the communications channels themselves. + Distributing processing and communications activity evenly across a computer network so that no single device is overwhelmed. + Load balancing is especially important for networks where it is difficult to predict the number of requests that are issued to a server. + Busy websites typically use two or more web servers in a load balancing scheme. + If one server starts to get swamped, requests are forwarded to another server with more capacity. + Load balancing can also refer to the communications channels themselves. @@ -170,12 +174,14 @@ logical topology - Also called signal topology. Every LAN has a topology, which refers to the way that the devices on a network are arranged and how they communicate with each other. The physical topology is the way that the workstations are connected to the network through the cables that transmit data: the physical structure of the network. The logical topology, in contrast, is the way that the signals act on the network media, or the way that the data passes through the network from one device to the next without regard to the physical interconnection of the devices. + Also called signal topology. + Every LAN has a topology, which refers to the way that the devices on a network are arranged and how they communicate with each other. + The physical topology is the way that the workstations are connected to the network through the cables that transmit data: the physical structure of the network. + The logical topology, in contrast, is the way that the signals act on the network media, or the way that the data passes through the network from one device to the next without regard to the physical interconnection of the devices. - login, log in diff --git a/en-US/Language.xml b/en-US/Language.xml index e9d6273..5b612b3 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -126,7 +126,9 @@ at this point in time - Do not use. In most cases, use "now". In some cases it is acceptable to use "at this point", for example, when you have reached a specific point in a procedure. + Do not use. + In most cases, use "now". + In some cases it is acceptable to use "at this point", for example, when you have reached a specific point in a procedure. @@ -136,7 +138,9 @@ automagic - Also, automagical. Both terms are slang. Do not use. + Also, automagical. + Both terms are slang. + Do not use. @@ -146,7 +150,11 @@ best-of-breed - Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type". Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. + Jargon. + Say exactly what you mean, for example, "the best product in its class" or "the best product of its type". + Other alternatives include best, foremost, most advanced, and optimum. + The category is usually implied. + Be wary of using superlatives without data to back up any claims. @@ -162,16 +170,17 @@ - + bottom line @@ -187,7 +196,8 @@ bucketize - Not a word. Try "categorize" or "organize into logical groups". + Not a word. + Try "categorize" or "organize into logical groups". @@ -207,7 +217,9 @@ check this site - Understood to mean "have a look at this website". The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. + Understood to mean "have a look at this website". + The preferred phraseology is "See www.somewhere.com for more information." + It is better to avoid "check" because it has so many meanings. @@ -218,7 +230,8 @@ core competency - Jargon, cold and impersonal. Better choices include "specialization", "skill", "strength", "expertise", and so on. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." + Jargon, cold and impersonal. + Better choices include "specialization", "skill", "strength", "expertise", and so on. @@ -238,7 +251,9 @@ dig deeper, delve deeper - "Visit the following web link to dig deeper into [subject] ...". Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." + "Visit the following web link to dig deeper into [subject] ...". + Using "dig deeper" may translate awkwardly. + Consider rewording: "For detailed information regarding [subject], see [link]." @@ -258,7 +273,8 @@ double-edged sword, double-bladed sword - If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. + If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. + Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. @@ -268,7 +284,9 @@ eat your own dogfood - Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. + Jargon. + It means to use your own products. + You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. @@ -278,7 +296,7 @@ enterprise-ready - Although Red Hat used to use this term to emphasize its products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. + Although Red Hat used to use this term to emphasize its products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you are calling this out as a key selling point. @@ -288,7 +306,8 @@ exceed your expectations - Vague. Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." + Vague. + Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." @@ -309,7 +328,8 @@ flog a dead horse - Do not use. Explain exactly what you mean, such as "a waste of effort". + Do not use. + Explain exactly what you mean, such as "a waste of effort". @@ -319,7 +339,9 @@ fly by the seat of your pants - Generally understood to mean "reacting to events as they occur". Difficult to offer alternatives without context. + Slang. + Generally understood to mean "reacting to events as they occur". + Difficult to offer alternatives without context. @@ -483,7 +505,8 @@ kettle of fish - Commonly used in the expression "a different kettle of fish", meaning "that's a different matter (altogether)". Depending on the context, try to use "topic", "subject", "matter", or something similar. + Commonly used in the expression "a different kettle of fish", meaning "that is a different matter (altogether)". + Depending on the context, use "topic", "subject", "matter", or something similar. @@ -493,7 +516,8 @@ leverage - Avoid. Alternatives include "use" and "take advantage of". + Avoid. + Alternatives include "use" and "take advantage of". @@ -637,7 +661,8 @@ ready to rumble - "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start". + "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. + In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start". @@ -689,7 +714,9 @@ shy of - Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark", meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have fewer than the minimum required number. Avoid this terminology and use more easily understood terms; it will help translators and also those reading English documentation who are unfamiliar with such slang. + Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark", meaning that he did not quite succeed. + Also, to be "a few items shy of what is required" means to have fewer than the minimum required number. + Avoid this terminology and use more easily understood terms; it helps translators and also those reading English documentation who are unfamiliar with such slang. @@ -773,7 +800,8 @@ under the covers - This refers to something being out of plain sight or not immediately obvious. For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you can't see or are not aware of, to make that action of command possible. + This refers to something being out of plain sight or not immediately obvious. + For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you cannot see or are not aware of, to make that action of command possible. @@ -783,7 +811,9 @@ value-added - Jargon. Say "added value" or "valuable". Or be more specific, for example, "adds value by improving productivity". + Jargon. + Say "added value" or "valuable". + Or be more specific, for example, "adds value by improving productivity". @@ -839,11 +869,10 @@
-
Phrasal Verbs - Avoid using a two-word verb form (a phrasal verb) if a one-word equivalent exists. + Avoid using two-word verb forms (phrasal verbs) if a one-word equivalent exists. @@ -978,19 +1007,28 @@ Follow these guiding principles: - Do not use the terms "white" or "black" in a context where white is represented as good or black is represented as bad, such as "whitelist" and "blacklist". Such usage reinforces a model that promotes racial bias. + Do not use the terms "white" or "black" in a context where white is represented as good or black is represented as bad, such as "whitelist" and "blacklist". + Such usage reinforces a model that promotes racial bias. For alternatives, choose words that describe the action that is taken or the function that is performed, rather than a metaphor for that action or function, for example "allowlist" instead of "whitelist", or "blocklist" or "denylist" instead of "blacklist". - Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill. + Do not use "master" when it is paired with "slave". + Such use diminishes the horror of the dehumanizing practice of slavery. + Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill. - Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". Avoid binary gendered language, such as "he" or "she", except to refer to a specific named person. Do not use "he or she". Instead, use the ungendered "they" as the preferred pronoun. + Avoid gender bias. + As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. + Thus, instead of using "man hours", use "labor hours" or "person hours". + Avoid binary gendered language, such as "he" or "she", except to refer to a specific named person. + Do not use "he or she". + Instead, use the ungendered "they" as the preferred pronoun. - Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. + Avoid neurodiversity bias. + For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. Avoid superlatives in job titles and descriptions, especially problematic terms such as "guru", "ninja", "rockstar", or "evangelist". @@ -1000,11 +1038,11 @@ -
Avoiding Redundant Words - Avoid redundant words, such as "actually", "really", "simply" and "very". They are typically filler words that add no value to a sentence. + Avoid redundant words, such as "actually", "really", "simply", and "very". + They are typically filler words that add no value to a sentence. Redundant words might also occur where two words or phrases are used that mean approximately the same thing, such as "revert back" versus "revert", or that add nothing to the sentence, such as "located on" versus "on". @@ -1035,8 +1073,8 @@ - Restore the LUKS2 header to the encrypted volume located on the `/dev/sda1` partition. - Restore the LUKS2 header to the encrypted volume on the `/dev/sda1` partition. + Restore the LUKS2 header to the encrypted volume located on the /dev/sda1 partition. + Restore the LUKS2 header to the encrypted volume on the /dev/sda1 partition. @@ -1057,7 +1095,8 @@ Capitalizing Proper Nouns - In some cases it is not clear if a term refers to a concept or a proper noun or product name. By using the correct capitalization, you will help translators identify untranslatable proper nouns and Red Hat product names. + In some cases it is not clear if a term refers to a concept or a proper noun or product name. + By using the correct capitalization, you help translators identify untranslatable proper nouns and Red Hat product names.
@@ -1088,12 +1127,13 @@ - Avoid Stating that Something Is Easy - Avoid stating that a task is easy to do or that a product is easy to use. Avoid "friendly" and "user-friendly" and similar terms. Focus instead on how to accomplish a task or on relevant features of a product. + Avoid stating that a task is easy to do or that a product is easy to use. + Avoid "friendly" and "user-friendly" and similar terms. + Focus instead on how to perform a task or on relevant features of a product.
@@ -1135,7 +1175,10 @@ Homographic Verbs - The verb "may" might indicate possibility or grant permission. Similarly, "should" might imply a recommendation or express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. + The verb "may" might indicate possibility or grant permission. + Similarly, "should" might imply a recommendation or express obligation or expectation. + A sentence containing one of these verbs often has a double meaning. + Avoid these types of words.
@@ -1190,7 +1233,7 @@ Homonymity - When a single term has multiple meanings, be explicit in order to differentiate between them. + When a single term has multiple meanings, be explicit to differentiate between them.
@@ -1408,7 +1451,9 @@ Synonymity - Sometimes multiple terms have a single meaning. If terms are used inconsistently, users (and translators) will assume they refer to different things. It is best to use a single term for a single concept throughout. + Sometimes multiple terms have a single meaning. + If terms are used inconsistently, users (and translators) might assume they refer to different things. + It is best to use a single term for a single concept throughout. For example, "Administration UI" and "Administration Console" could both be used to refer to a single application or to different applications. For this reason it is important that writers choose the most suitable term for each situation and use it consistently. @@ -1614,4 +1659,4 @@ - \ No newline at end of file + From 1e7ae192559f0f6e51ed57eb6321f78c085be624 Mon Sep 17 00:00:00 2001 From: daobrien Date: Thu, 2 Feb 2023 22:11:42 +1000 Subject: [PATCH 05/79] s/may/might/ per Julian's review. --- en-US/Language.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Language.xml b/en-US/Language.xml index 5b612b3..d0d2035 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -252,7 +252,7 @@ "Visit the following web link to dig deeper into [subject] ...". - Using "dig deeper" may translate awkwardly. + Using "dig deeper" might translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." From d82ff7a63ef346d2dcb69a314d46dca08a1cc709 Mon Sep 17 00:00:00 2001 From: daobrien Date: Fri, 3 Feb 2023 00:00:57 +1000 Subject: [PATCH 06/79] Working on #457 Run Vale of the style guide part 3. --- en-US/M.xml | 30 ++++++++++++++++++++--------- en-US/N.xml | 22 ++++++++++++---------- en-US/O.xml | 44 ++++++++++++++++++++++++++----------------- en-US/Objectives.xml | 14 ++++++++++---- en-US/P.xml | 22 +++++++++++++--------- en-US/Punctuation.xml | 32 ++++++++----------------------- en-US/Q.xml | 9 +++------ 7 files changed, 94 insertions(+), 79 deletions(-) diff --git a/en-US/M.xml b/en-US/M.xml index 63d7d08..e35a362 100644 --- a/en-US/M.xml +++ b/en-US/M.xml @@ -41,12 +41,13 @@ - master - 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". Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill. @@ -58,7 +59,9 @@ matrixes - 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". @@ -125,18 +128,20 @@ Objects on which data can be stored. These include hard disks, CDs, and tapes. - - 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). + - 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. @@ -254,7 +259,10 @@ mouse button - n. 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. + n. 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. @@ -264,7 +272,9 @@ Mozilla Firefox - 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". @@ -274,7 +284,9 @@ Mozilla Thunderbird - 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". diff --git a/en-US/N.xml b/en-US/N.xml index 94d16d7..ecac797 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -10,7 +10,8 @@ navigate to - 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." Do not use "Go to", or "point to", or other variations. @@ -22,7 +23,8 @@ needs, needs to be, need to - Avoid when possible. Suggested alternatives include "must" or "required". + Avoid when possible. + Use "must" or "required" or similar. @@ -56,10 +58,13 @@ NFS - 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. - 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. @@ -111,17 +116,14 @@ number sign - 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 ), 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 ), 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. - - - diff --git a/en-US/O.xml b/en-US/O.xml index 49ce877..9cd08ac 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -51,15 +51,13 @@ offline backup - 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. - 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. - - + 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. @@ -69,12 +67,13 @@ OK - When referring to the OK button, it is not necessary to use "button" in the sentence. For example, "Click OK to close the dialog box." + When referring to the OK button, it is not necessary to use "button" in the sentence. + For example, "Click OK to close the dialog box." - 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". - @@ -92,7 +91,8 @@ once - 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". 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". @@ -162,7 +162,9 @@ on-the-fly - 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. @@ -172,7 +174,10 @@ oops - 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". @@ -244,10 +249,11 @@ open source way - A phrase that was coined by the Red 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 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." - 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 Open Source Initiative, 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 Open Source Initiative, to avoid diluting the legal meaning of the term "open source". @@ -287,7 +293,10 @@ overcloud - n. 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 . + n. Always lowercase. + This is a concept, not a technology or product name. + Being a common noun, it normally requires an article. + See also . @@ -297,7 +306,8 @@ override - Correct. Do not use "over-ride" or "over ride". + Correct. + Do not use "over-ride" or "over ride". diff --git a/en-US/Objectives.xml b/en-US/Objectives.xml index fc7a45f..a4b0796 100644 --- a/en-US/Objectives.xml +++ b/en-US/Objectives.xml @@ -6,7 +6,10 @@ Objectives of this Guide - The objective of the Red 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 Hat documentation is: + The objective of the Red 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 Hat documentation is: - Accurate and consistent + Accurate and consistent. - 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. @@ -44,7 +47,10 @@ Readability - 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 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 Hat guide should have a Gunning Fog index of 9-12. diff --git a/en-US/P.xml b/en-US/P.xml index 1f2f11d..5b48e1e 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -72,10 +72,13 @@ plain text - n. Two words. In most cases, do not use "plaintext", "cleartext", or other variants. + n. Two words. + In most cases, do not use "plaintext", "cleartext", or other variants. - Cryptographers distinguish between "cleartext" (unencrypted data) and "plaintext" (unencrypted data as input to an encryption algorithm). Red 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 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". @@ -85,9 +88,9 @@ please - Do not use. Instead of saying "Please see the Getting Started Guide", use "See the Getting Started Guide." + Do not use. + Instead of saying "Please see the Getting Started Guide", use "See the Getting Started Guide." - 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. @@ -109,12 +112,11 @@ plug-in - n. Write hyphenated. Do not use "plugin". + n. Write hyphenated. + Do not use "plugin". A hardware or software module that adds a specific feature or service to a larger system. - - @@ -173,10 +175,12 @@ n. 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 Open Power Foundation if unsure. - 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". - 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  Hat Enterprise Linux runs on 64-bit IBM Power Series hardware in most cases. diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 1ec0e8c..4e0020a 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -419,11 +419,13 @@ - If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. If not, the period goes outside. + If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. + If not, the period goes outside. - Do not use "(s)" in parentheses to denote a plural. If something can be singular or plural, make it plural. + Do not use "(s)" in parentheses to denote a plural. + If something can be singular or plural, make it plural. @@ -470,13 +472,6 @@
Quotation Marks - When indicating the start or end of a direct quotation, use curly quotation marks. In all other contexts, such as when writing code samples, code syntax, hexadecimal numbers, or hypertext links, use straight quotation marks. @@ -506,7 +501,7 @@ If you use the keyword operand PGMID="PAYCOM", you must ... --> - Julius Caesar said, “I came. I saw. I conquered.” + Julius Caesar said, "I came. I saw. I conquered." @@ -521,15 +516,8 @@ - - Do not put quotation marks around cliches or slang terms (in fact, avoid using cliches and slang as it makes the translation of content more difficult). - -Remove this sentence, and leave it to chapter 4 to cover avoidance of slang. +--> - - A word or words being introduced to readers should not be placed in quotation marks. In DocBook, use the <firstterm> element for first reference. If you are writing outside of the SGML tagging environment, use quotation marks for first references. Subsequent references do not need quotation marks or the <firstterm> element. - -Deleted paragraph now that DocBook tagging no longer applies. -->
Apostrophes @@ -554,7 +542,6 @@ Deleted paragraph now that DocBook tagging no longer applies. -->
-
Exclamation Points @@ -563,7 +550,6 @@ Deleted paragraph now that DocBook tagging no longer applies. -->
-
Referring to Punctuation Marks @@ -593,14 +579,12 @@ Deleted paragraph now that DocBook tagging no longer applies. -->
-
Names of Punctuation Marks and Special Characters Use the names in the following table to refer to punctuation marks or special characters: -
Names of Punctuation Marks and Special Characters @@ -667,7 +651,7 @@ Deleted paragraph now that DocBook tagging no longer applies. --> ✓ - Check mark + Checkmark @@ -789,4 +773,4 @@ Deleted paragraph now that DocBook tagging no longer applies. --> - \ No newline at end of file + diff --git a/en-US/Q.xml b/en-US/Q.xml index 32244f2..8ef1139 100644 --- a/en-US/Q.xml +++ b/en-US/Q.xml @@ -10,12 +10,8 @@ qeth - Lowercase at all times. + Always lowercase. - @@ -23,7 +19,8 @@ quiesce, quiescent - Use with caution. This term is readily understood in the context of databases and stateful systems, but in other contexts another term might be more suitable. + Use with caution. + This term is readily understood in the context of databases and stateful systems, but in other contexts another term might be more suitable. From 2733a9c828634eb6afb14775fb496d07d03cec08 Mon Sep 17 00:00:00 2001 From: daobrien Date: Fri, 3 Feb 2023 21:52:50 +1000 Subject: [PATCH 07/79] Closes #457 Run Vale over the style guide, part 3. --- en-US/R.xml | 13 ++++++++++--- en-US/Revision_History.xml | 6 +++--- en-US/S.xml | 26 +++++++++++++++++--------- 3 files changed, 30 insertions(+), 15 deletions(-) diff --git a/en-US/R.xml b/en-US/R.xml index 21d275f..1d43bc7 100644 --- a/en-US/R.xml +++ b/en-US/R.xml @@ -23,7 +23,10 @@ Correct. Do not use "RAMdisk", "ramdisk", or "RAdisk". - Refers to RAM that is configured to simulate a disk drive. You can access files on a RAM disk as you would access files on a real disk. RAM disks, however, are approximately a thousand times faster than hard disk drives. They are particularly useful, therefore, for applications that require frequent disk accesses. + Refers to RAM that is configured to simulate a disk drive. + You can access files on a RAM disk as you would access files on a real disk. + RAM disks, however, are about a thousand times faster than hard disk drives. + They are particularly useful, therefore, for applications that require frequent disk accesses. @@ -135,7 +138,8 @@ remote access server - A dedicated server to handle users who are not on a LAN but who need remote access to it. With a remote access server, users can gain access to files and print services on the LAN from a remote location. + A dedicated server to handle users who are not on a LAN but who need remote access to it. + With a remote access server, users can access files and print services on the LAN from a remote location. @@ -211,7 +215,10 @@ RPM - Initialism for RPM Package Manager. RPM manages files in the RPM format, known as RPM packages. Note: RPM packages are known informally as rpm files, but this informal usage is not used in Red Hat documentation, to avoid confusion with the command name. Files in RPM format are referred to as "RPM packages". + Initialism for RPM Package Manager. + RPM manages files in the RPM format, known as RPM packages. + Note: RPM packages are known informally as rpm files, but this informal usage is not used in Red Hat documentation, to avoid confusion with the command name. + Files in RPM format are referred to as "RPM packages". diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml index 7c735c6..3bab0ad 100644 --- a/en-US/Revision_History.xml +++ b/en-US/Revision_History.xml @@ -86,13 +86,13 @@ BZ 927031: Review 'The Page Test' and 'The Reverse Test' entries. BZ 1020131: Section 6.2 The Page Test is not sensible. BZ 1070003: Add entry for "Internet of Things (IoT)". - Relocate some slang and jargon terms to appropriate section. + Move some slang and jargon terms to appropriate section. BZ 1070001: Add entry for "untrusted". BZ 1064711: Update section on hyphenation. BZ 1061598: Add section about correct use of Introductions, Titles, and other headings. Removed <quote> tags from body text to follow own advice. Updated section on using tags with abbreviations and acronyms. - BZ 1028253: Document standard for user and host names in CLI examples. + BZ 1028253: Document standard for user and hostnames in CLI examples. @@ -309,7 +309,7 @@ BZ 921826 Add entry for "best practices" to chapter "Avoiding Slang". BZ 916000 Add entry for correct use of product version numbers to Design chapter. - Fix entry for VDSM; it's not an acronym. + Fix entry for VDSM; not an acronym. BZ 909015 Entry for "refer to" conflicts with IBM style guide. Update some punctuation standards and cross references. diff --git a/en-US/S.xml b/en-US/S.xml index 46da1b8..20b92eb 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -141,7 +141,7 @@ Abbreviation of Security-Enhanced Linux. SELinux uses Linux Security Modules (LSM) in the Linux kernel to provide a range of minimum-privilege-required security policies. - Do not use any other alternatives. + Do not use any other forms. @@ -216,7 +216,9 @@ Pronounced "shä" and thus requires "an" as the indefinite article. - SHA stands for Secure Hash Algorithm; each is a cryptographic hash function. SHA2 variants are often specified by using their digest size, in bits, as the trailing number, in lieu of "2". Thus "SHA224", "SHA256", "SHA384", and "SHA512" are considered correct when referring to these specific hash functions. + SHA stands for Secure Hash Algorithm; each is a cryptographic hash function. + SHA2 variants are often specified by using their digest size, in bits, as the trailing number, instead of "2". + Thus "SHA224", "SHA256", "SHA384", and "SHA512" are considered correct when referring to these specific hash functions. See for full details. @@ -302,7 +304,9 @@ should - Do not use if it is something the user must do. For example, "You should make a backup" is a suggestion, while "You must make a backup" is a requirement. See also . + Do not use if it is something the user must do. + For example, "You should make a backup" is a suggestion, but "You must make a backup" is a requirement. + See also . @@ -351,7 +355,9 @@ since, as, because - Do not use "since" or "as" to mean "because"; it is ambiguous. Use "because" to refer to a reason. Use "since" or "as" to refer to the passage of time. + Do not use "since" or "as" to mean "because"; it is ambiguous. + Use "because" to refer to a reason. + Use "since" or "as" to refer to the passage of time. @@ -398,12 +404,13 @@ - slave - Do not use. It diminishes the horror of the dehumanizing practice of slavery. Use another term such as "worker", "child", "helper", "replica", or "secondary (server, node, process, or other noun)". + Do not use. + It diminishes the horror of the dehumanizing practice of slavery. + Use another term such as "worker", "child", "helper", "replica", or "secondary (server, node, process, or other noun)". @@ -587,11 +594,11 @@ a programming and technical sense, it also means "Run the sourcestand-alone - adj. Write hyphenated. Do not use "standalone". + adj. Hyphenate. + Do not use "standalone". Refers to something that is self-contained, or that does not require any other devices to function. - For example, a smartphone is a stand-alone device because it does not require a computer, printer, modem, or other device. A printer, on the other hand, is not a stand-alone device because it requires a computer to feed it data. @@ -617,7 +624,8 @@ a programming and technical sense, it also means "Run the sourcestart up - v. Do not use. Instead, use "activate" or "invoke". + v. Do not use. + Instead, use "start", "activate", or "invoke". From 06426b0bad5dd69ab4da9dafc6272c244a41f2de Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 6 Feb 2023 11:22:09 +1000 Subject: [PATCH 08/79] Remove spurious space. --- en-US/P.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/P.xml b/en-US/P.xml index 5b48e1e..d1e5df7 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -180,7 +180,7 @@ 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". - Note: The PowerPC version of Red  Hat Enterprise Linux runs on 64-bit IBM Power Series hardware in most cases. + Note: The PowerPC version of Red Hat Enterprise Linux runs on 64-bit IBM Power Series hardware in most cases. From bd57d5745c71b92df04cdce3900b2520d1bc3ba6 Mon Sep 17 00:00:00 2001 From: daobrien Date: Thu, 9 Feb 2023 21:20:23 +1000 Subject: [PATCH 09/79] Closes #458 Run Vale over style guide part 4. --- en-US/T.xml | 13 ++++++------- en-US/Translation.xml | 19 ++++++++++--------- en-US/U.xml | 25 ++++++++++++++++++------- en-US/V.xml | 5 ++++- en-US/W.xml | 20 ++++++++++++-------- en-US/WUG_Intro.xml | 8 ++++++-- en-US/XYZ.xml | 6 ++++-- 7 files changed, 60 insertions(+), 36 deletions(-) diff --git a/en-US/T.xml b/en-US/T.xml index 0d2b5b3..0bc0ea7 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -149,32 +149,31 @@ - - time frame (n.) + time frame - Correct. Do not use "timeframe" or "time-frame". + n. Correct. Do not use "timeframe" or "time-frame". - time zone (n.) + time zone - Correct. Do not use "timezone" or "time-zone". + n. Correct. Do not use "timezone" or "time-zone". - token-ring (n.) + token-ring - When capitalized, Token-Ring refers to the PC network architecture that IBM developed. The IBM Token-Ring specification is standardized by the IEEE as the IEEE 802.5 standard. + n. When capitalized, Token-Ring refers to the PC network architecture that IBM developed. The IBM Token-Ring specification is standardized by the IEEE as the IEEE 802.5 standard. diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 0093639..e604ce1 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -18,18 +18,20 @@
Using and Formatting Lists - Lists appear in a range of formats, such as series, ordered, unordered (itemized), and so on. Avoid using itemized lists to format a single sentence. Some translation tools display list items and the introductory sentence (or sentence stem) as individual sentences for translation. If they are not complete sentences, they can be difficult to translate. + Lists appear in a range of formats, such as series, ordered, unordered (bulleted), and so on. + Avoid using bulleted lists to format a single sentence. + Some translation tools display list items and the introductory sentence (or sentence stem) as individual sentences for translation. + If they are not complete sentences, they can be difficult to translate. The following general guidelines apply to lists: - Itemized lists + Bulleted lists - They appear as a bulleted list. - Use this list type for three or more entries where order is not important, or in a demonstration section when students are encouraged not to perform steps but to watch the instructor instead. + Use this list type for three or more entries where order is not important. Titles are optional. @@ -38,7 +40,7 @@ Ordered lists - They appear as a numbered list. + These appear as numbered lists. Use this list type for multiple entries if you need to refer to one of the entries from elsewhere in your document, or where order is important. For example, if you need to list the order of operations that are required to prepare for an installation, or list a sequence of events that occurs. Titles are optional. @@ -49,7 +51,7 @@ Variable lists - They appear as a list of terms followed by definitions. + These appear as a list of terms followed by definitions. Use this list type to list and describe a series of terms, such as variables, command options or arguments, and similar items. Titles are optional. (This list is written as a variable list.) @@ -62,7 +64,7 @@ Procedures - They appear as a list of numbered steps. + These appear as a list of numbered steps. Procedures always include a title, and are used to list the required steps to achieve a task. @@ -70,11 +72,10 @@ You can nest lists, but try to keep the number of levels to two or fewer. - To nest procedures in DocBook, use <substep> elements.
Formatting Lists for Readability - It is important to provide sufficient spacing between elements in your documents to facilitate reading and comprehension. + It is important to provide enough spacing between elements in your documents to facilitate reading and comprehension. You can include a lot of information in a few short paragraphs but readers need to be able to process that information in chunks. The same consideration applies to lists. diff --git a/en-US/U.xml b/en-US/U.xml index 935a9f1..5794a9f 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -20,10 +20,12 @@ UltraSPARC - Correct. Do not use "ULTRASPARC", "UltraSparc", or other variations. + Correct. + Do not use "ULTRASPARC", "UltraSparc", or other variations. - UltraSPARC is a trademark of SPARC International, Inc., and is used under license by Sun Microsystems, Inc. Products that bear the SPARC trademarks are based on an architecture developed by Sun Microsystems, Inc. + UltraSPARC is a trademark of SPARC International, Inc., and is used under license by Sun Microsystems, Inc. + Products that bear the SPARC trademarks are based on an architecture developed by Sun Microsystems, Inc. @@ -33,7 +35,10 @@ undercloud - n. Always lowercase. It is a concept, not a technology or product name. Being a common noun, it requires an article in most cases. See also . + n. Always lowercase. + It is a concept, not a technology or product name. + Being a common noun, it normally requires an article. + See also . @@ -185,10 +190,14 @@ user interface - n. Correct. Do not use "user-interface" or "userinterface". + n. Correct. + Do not use "user-interface" or "userinterface". - The junction between a user and a computer program. An interface is a set of commands or menus through which a user communicates with a program. In a command-driven interface, you enter commands. In a menu-driven interface, you select command choices from various menus that are displayed on the screen. + The junction between a user and a computer program. + An interface is a set of commands or menus through which a user communicates with a program. + In a command-driven interface, you enter commands. + In a menu-driven interface, you select command choices from various menus that are displayed on the screen. @@ -198,7 +207,7 @@ username - n. One word in most cases. + n. Usually one word. Capitalize the "U" at the beginning of a sentence. See the IBM Style Guide for more information. @@ -210,7 +219,9 @@ user space - n. Correct when used as a noun. When used as a modifier, use the hyphenated form, "user-space". Do not use "userspace". + n. Correct when used as a noun. + When used as a modifier, use the hyphenated form, "user-space". + Do not use "userspace". diff --git a/en-US/V.xml b/en-US/V.xml index e57e6f5..e43993f 100644 --- a/en-US/V.xml +++ b/en-US/V.xml @@ -58,7 +58,10 @@ Only use "vim" (all lowercase) when referring to the command to start the application. - Vim is an acronym, derived from Vi IMproved. (In the original 1991 release for the Amiga platform, the acronym was derived from Vi IMitation. It became Vi IMproved when ported to various UNIX-based operating systems in 1992.) Despite being an acronym, and despite the first word of the "About" text that appears when you start the editor, the standard, proper noun-derived, mixed-case spelling has been in use since its release on the Amiga. + Vim is an acronym, derived from Vi IMproved. + (In the original 1991 release for the Amiga platform, the acronym was derived from Vi IMitation. + It became Vi IMproved when ported to various UNIX-based operating systems in 1992.) + Despite being an acronym, and despite the first word of the "About" text that appears when you start the editor, the standard, proper noun-derived, mixed-case spelling has been in use since its release on the Amiga. diff --git a/en-US/W.xml b/en-US/W.xml index 7543d1b..fea3c32 100644 --- a/en-US/W.xml +++ b/en-US/W.xml @@ -63,7 +63,9 @@ web page - n. Two words. Capitalize the "W" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. + n. Two words. + Capitalize the "W" at the beginning of a sentence. + If part of a proper noun, capitalize accordingly. @@ -73,7 +75,8 @@ web UI - Correct. Use this term to refer to a browser-based interface to a software application, even if that application has no connection to the web. + Correct. + Use this term to refer to a browser-based interface to a software application, even if that application has no connection to the web. Do not hyphenate the abbreviation or use the one-word form. @@ -97,7 +100,7 @@ whether - Use “whether” instead of “if” to refer to a choice or to alternatives. + Use "whether" instead of "if" to refer to a choice or to alternatives. For example, instead of "Test if authenticated FTP access is restored", write "Test whether authenticated FTP access is restored". @@ -109,15 +112,14 @@ while - In technical content, use “while” only to indicate that many tasks or processes occur at the same time. - For example, instead of "While most targets use one target portal group (TPG), advanced configurations might define multiple TPGs", write "Although most targets use one target portal group (TPG), advanced configurations might define multiple TPGs". + In technical content, use "while" only to indicate that many tasks or processes occur at the same time. + For example, instead of "While most targets use one target portal group (TPG), advanced configurations might define multiple TPGs", write "Although most targets use one target portal group (TPG), advanced configurations might define multiple TPGs." - whitelist @@ -125,7 +127,8 @@ Do not use. Use "allowlist". - Do not use the terms "white" or "black" in a context where white is represented as good or black is represented as bad. Such usage reinforces a model that promotes racial bias. + Do not use the terms "white" or "black" in a context where white is represented as good or black is represented as bad. + Such usage reinforces a model that promotes racial bias. @@ -138,7 +141,8 @@ Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition. - For example: Who owns this phone? To whom does this phone belong? + For example: Who owns this phone? + To whom does this phone belong? diff --git a/en-US/WUG_Intro.xml b/en-US/WUG_Intro.xml index 3bafcfd..834f63b 100644 --- a/en-US/WUG_Intro.xml +++ b/en-US/WUG_Intro.xml @@ -6,14 +6,18 @@ Usage Dictionary - This page provides guidelines for the correct use of common terms in Red Hat documentation, which terms to avoid, and the preferred spelling where variations exist. This page is constantly evolving, and open to discussion and improvement. + This page provides guidelines for the correct use of common terms in Red Hat documentation, which terms to avoid, and the preferred spelling where variations exist. + This page is constantly evolving, and open to discussion and improvement. A note about trademarks - The status of a trademark can vary from country to country. Therefore, do not attach the symbols for trademark or registered trademark (™ and ®) to any third-party trademarks that you mention in your document unless Red Hat legal asks you to do so. In XML terms, this means that you should not generally tag trademarks with the <trademark> tag. We do mark Red Hat's own trademarks. See Copyright Notices and Trademark Legends for more information. + The status of a trademark can vary from country to country. + Therefore, do not attach the symbols for trademark or registered trademark (™ and ®) to any third-party trademarks that you mention in your document unless Red Hat legal asks you to do so. + We do mark Red Hat trademarks. + See Copyright Notices and Trademark Legends for more information. diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index 8ce468a..c7082ee 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -70,7 +70,8 @@ YAML - Recursive acronym for "YAML Ain't Markup Language." Expand on first use only. + Recursive acronym for "YAML Ain't Markup Language." + Expand on first use only. @@ -80,7 +81,8 @@ you - Use second person wherever possible. Do not use "I", "we", "he", or "she." + Use second person wherever possible. + Do not use "I", "we", "he", or "she." From 3d9f18cbc346ae3e6fa757bba78b47f2bef4d229 Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 13 Feb 2023 15:16:49 +1000 Subject: [PATCH 10/79] Closes #365 Remove DocBook references. --- en-US/Design.xml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 7bb1591..4648444 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -63,7 +63,7 @@ Gerunds should be avoided elsewhere. See . - + File Names, Commands, and Related Terms @@ -567,10 +567,13 @@ $ vi myFile.txt To describe how to view and edit files, such as configuration files, scripts, and so on, do not include editor names as part of the guidance, unless the topic is about a specific editor, or is otherwise necessary to achieve a wanted result. - For example, do not refer to cat or vi if you need to tell readers to "view the my-script file". If you need to tell readers to edit a file and add or remove content, write "Edit the my-script file and add the following content:" and then include the required content in a <screen> block. Use <code> tags to highlight the text to change. Include some surrounding text in the file for context. Do not use line numbers as a reference point because they can change. + For example, do not refer to cat or vi if you need to tell readers to "view the my-script file". + If you need to tell readers to edit a file and add or remove content, write "Edit the my-script file and add the following content:" and then include the required content in a code block and highlight the text to change. + Include some surrounding text in the file for context. + Do not use line numbers as a reference point because they can change. - If the file to edit is empty or does not exist, do not use <code> tags to highlight any content to add. + If the file to edit is empty or does not exist, do not highlight any content to add. You can also use here documents to describe how to create a file with required content. The syntax of here documents varies by system, shell, language, and so on. The following example creates the my-script file in the current directory, with the example content. From 85fc2f48e2b0affaafdbf637aac4de0c2ee6224f Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 13 Feb 2023 15:58:38 +1000 Subject: [PATCH 11/79] Closes #78 Update entry for "virtualized". Basically copy/paste from corp guide. --- en-US/V.xml | 49 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 39 insertions(+), 10 deletions(-) diff --git a/en-US/V.xml b/en-US/V.xml index e43993f..e6ae9b1 100644 --- a/en-US/V.xml +++ b/en-US/V.xml @@ -10,7 +10,8 @@ VAR - Acronym for value-added reseller. Same as OEM (original equipment manufacturer). + Acronym for value-added reseller. + Same as OEM (original equipment manufacturer). @@ -20,7 +21,10 @@ VDSM - Initialism for Virtual Desktop Server Management. Do not spell out this initialism. Using the term "virtual desktop" in this context has negative marketing implications. Use VDSM without expansion. + Initialism for Virtual Desktop Server Management. + Do not spell out this initialism. + Using the term "virtual desktop" in this context has negative marketing implications. + Use VDSM without expansion. @@ -30,7 +34,9 @@ vi - Correct. Use all lowercase letters. Do not use "VI" (all caps). + Correct. + Use all lowercase letters. + Do not use "VI" (all caps). @@ -40,10 +46,15 @@ video mode - Correct. Do not use "video-mode" or "videomode". + Correct. + Do not use "video-mode" or "videomode". - The setting of a video adapter. Most video adapters can run in either text mode or graphics mode. In text mode, a monitor can display only ASCII characters. In graphics mode, a monitor can display any bit-mapped image. In addition to the text and graphics modes, video adapters offer different modes of resolution and color depth. + The setting of a video adapter. + Most video adapters can run in either text mode or graphics mode. + In text mode, a monitor can display only ASCII characters. + In graphics mode, a monitor can display any bit-mapped image. + In addition to the text and graphics modes, video adapters offer different modes of resolution and color depth. @@ -66,12 +77,25 @@ + + + virtual, virtualized + + + "Virtual" is the preferred adjective. + Use "virtualized" to indicate a component or concept previously existed in non-virtual (physical) form. + (Note: Use the American spelling of this word even in documents that are for audiences that use British English spellings. + This is to avoid the visual inconsistency of talking about your "virtualisation" with "Red Hat Virtualization." + Never change the product name spelling.) + + virtual console - Correct. Do not use "virtual-console" or "Virtual Console" for general use. + Correct. + Do not use "virtual-console" or "Virtual Console" for general use. It can be abbreviated to "VC" provided that the term is first introduced in the same content in its full version, such as "A virtual console (VC) is a shell prompt in a non-graphical environment. Multiple VCs can be accessed simultaneously." @@ -100,7 +124,8 @@ Refers to virtual hardware that consists of virtual CPUs, memory, devices, and so on. Do not use "guest virtual machine" except for specific emphasis that it is a guest. - It can be abbreviated to "VM" provided that the term is first introduced in the same content in its full version, and without any possible confusion with other terms, such as "virtual memory". Author discretion is recommended. + It can be abbreviated to "VM" provided that the term is first introduced in the same content in its full version, and without any possible confusion with other terms, such as "virtual memory". + Author discretion is recommended. @@ -110,7 +135,8 @@ virtual router - An abstract object managed by VRRP (virtual router redundancy protocol) that acts as a default router for hosts on a shared LAN. It consists of a Virtual Router Identifier and a set of associated IP addresses across a common LAN. + An abstract object managed by VRRP (virtual router redundancy protocol) that acts as a default router for hosts on a shared LAN. + It consists of a Virtual Router Identifier and a set of associated IP addresses across a common LAN. @@ -120,7 +146,8 @@ VNIC - Abbreviation for virtual network interface card. Use all uppercase characters for the abbreviation, but all lowercase for the expansion, except at the beginning of a sentence. + Abbreviation for virtual network interface card. + Use all uppercase characters for the abbreviation, but all lowercase for the expansion, except at the beginning of a sentence. @@ -130,7 +157,9 @@ VPN - Initialism for virtual private network, a network that uses public wires to connect nodes. For example, various systems can create networks with the internet as the medium for transporting data. These systems use encryption and other security mechanisms to ensure that only authorized users can access the network and that the data cannot be intercepted. + Initialism for virtual private network, a network that uses public wires to connect nodes. + For example, various systems can create networks with the internet as the medium for transporting data. + These systems use encryption and other security mechanisms to ensure that only authorized users can access the network and that the data cannot be intercepted. From 3335f18699a4577244534633563582ef318927fb Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 13 Feb 2023 16:25:57 +1000 Subject: [PATCH 12/79] Closes #355. Improve a bit of formatting. --- en-US/A.xml | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index 52368b4..2897ced 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -27,7 +27,6 @@ - agile @@ -121,7 +120,6 @@ The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . - For more information about Intel® trademarks, see and . @@ -145,7 +143,6 @@ - appendixes @@ -157,25 +154,23 @@ - Applixware From c9f5eb826a6f1f241ab2a790546d571188f04763 Mon Sep 17 00:00:00 2001 From: Christine Belzie <105683440+CBID2@users.noreply.github.com> Date: Thu, 22 Jun 2023 06:56:23 -0400 Subject: [PATCH 13/79] feat: Add advice on naming the default branch in an inclusive way. (#493) * feat: Add advice on naming the default branch in an inclusive way. * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --- en-US/Language.xml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/en-US/Language.xml b/en-US/Language.xml index d0d2035..f7f15ee 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1015,8 +1015,9 @@ Do not use "master" when it is paired with "slave". - Such use diminishes the horror of the dehumanizing practice of slavery. - Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill. + The master and slave mount propagation terminology that is used in Linux is problematic and divisive, and needs to be changed. + When naming the default branch name for a GitHub repository, use "main" instead of "master". + Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill. Avoid gender bias. From 560c4df18b4f3b32d31ca3d37eb92478dc66f7d2 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Fri, 23 Jun 2023 09:40:05 +0100 Subject: [PATCH 14/79] Updated section about writing titles (#492) * Updated section about writing titles * Reverted title ID * Further edits --- en-US/Design.xml | 45 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 4648444..8d9963c 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -47,13 +47,52 @@ - Verbs in Titles + Writing Effective Titles - Usually, you start a title with the gerund form of a verb, which ends with "-ing", for example "Creating Branches". Choose a verb that refers to specific actions that users take, such as "Configuring", "Creating", "Installing", and "Merging". + Use a title that represents the content. - The gerund verb form is not always required. For example, avoid verbs such as "Describing", "Introducing", and "Understanding", because they add little value. Instead, use a more specific verb or omit the verb. For example, instead of "Describing Initial Git Configuration", you can use "Initial Git Configuration". + Typically, the "ing" form of a verb is a good way to title larger chunks of content such as chapters and sections, for example "Creating Branches". Choose a verb that refers to specific actions that users take, such as "Configuring", "Creating", "Installing", and "Merging". + + + Activities and subtasks that the user should perform can alternatively use an imperative verb for clarity. Imperative verbs are prescriptive, such as "Create" or "Delete". Example: "Assess the Health of an OpenShift Cluster". + + + 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 "Installation Overview" or "The OpenShift Web Console." + +
+ + + + + + + Example + Improvement + + + + + + + Understanding OpenShift Users and Groups + OpenShift Users and Groups + + + + Introducing Cluster Updates + Cluster Updates + + + + + + + +
+ + In training content, avoid using a verb such as "Discussing" or "Demonstrating" in objectives for students. Such verbs might refer instead to what the instructor or the course content covers, or to a student group activity in class. See the IBM Style Guide for more information. From 39931098e540ecc5cd8ac3b3f4d9b24cadc5925f Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Fri, 30 Jun 2023 10:28:05 +0100 Subject: [PATCH 15/79] Updated guidance on continuation prompts (#494) --- en-US/Design.xml | 43 ++++++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 8d9963c..d355102 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -392,6 +392,11 @@
Documenting Multiple or Long Commands + + + The following guidance differs from previous guidance on the subject. + + Sometimes you need to show how to use long commands that extend over two or more lines, or that include several commands in a single example. If the commands are relatively short and straightforward, then include the commands on consecutive lines. @@ -404,11 +409,12 @@ $ vi myFile.txt - - If the commands are long, complex, or wrap over multiple lines, then the following design options are available. + + If the commands are long, complex, or wrap over multiple lines, then use the following design: + - + Use line continuation characters without the associated PS2 prompts. - + You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required. - You can use this option for any of these designs. + -Wrapping Long Commands with Continuation Characters and PS2 Prompts + - + -# tar --selinux -czvf config_files.tar.gz /etc/katello \ +# tar --selinux -czvf config_files.tar.gz /etc/katello \ > /etc/elasticsearch /etc/candlepin /etc/pulp /etc/gofer \ > /etc/grinder /etc/pki/katello /etc/pki/pulp /etc/qpidd.conf \ > /etc/sysconfig/katello /etc/sysconfig/elasticsearch \ -> /root/ssl–build /var/www/html/pub/* /var/lib/katello - +> /root/ssl-build /var/www/html/pub/* /var/lib/katello + Wrapping Long Commands Without Continuation Characters or PS2 Prompts This example uses neither continuation characters nor PS2 prompts, but it does show how to use line indentation to help to clarify long commands. -# cd /var/lib/katello +# cd /var/lib/katello -# myCommand --option funky --color=true - --config_file=/home/user/config.conf - --output_file=/home/user/output.txt +# myCommand --option funky --color=true + --config_file=/home/user/config.conf + --output_file=/home/user/output.txt - + --> Wrapping Long Commands with Continuation Characters and Without PS2 Prompts This example uses continuation characters but not PS2 prompts. - + [root@node]# cephadm bootstrap --mon-ip=MON_IP --registry-url=registry.redhat.io \ --registry-username=REGISTRY_USERNAME --registry-password=REGISTRY_PASSWORD \ --initial-dashboard-password=DASHBOARD_PASSWORD --dashboard-password-noupdate \ From 05c8e0665365f12ba365297b8e04089df51fd245 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 5 Jul 2023 16:11:55 +0100 Subject: [PATCH 16/79] Various fixes for 6.1 release (#495) * Various fixes for 6.1 release * XML fix --- en-US/B.xml | 2 +- en-US/Design.xml | 12 ++++++------ en-US/E.xml | 4 ++-- en-US/Grammar.xml | 2 +- en-US/Language.xml | 2 +- en-US/N.xml | 2 +- en-US/New.xml | 2 +- en-US/O.xml | 2 +- 8 files changed, 14 insertions(+), 14 deletions(-) diff --git a/en-US/B.xml b/en-US/B.xml index 31cf889..ed2bc30 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -382,7 +382,7 @@ See for more information on this file system. - See for a list of file system names and how to present them. + See for a list of file-system names and how to present them. diff --git a/en-US/Design.xml b/en-US/Design.xml index d355102..1caddc4 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -709,7 +709,7 @@ $ vi myFile.txt - 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: John Doe, Sunni Koning, Huong Sabo, and Jerlene Paluch. John is a department manager and needs read access to the accounting directory. Sunni is the lead accountant and needs both read and write access. + 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: Sunni Koning, Huong Sabo, and Jerlene Paluch. Sunni is a department manager and needs read access to the accounting directory. Huong is the lead accountant and needs both read and write access. Choosing a Realistic Name @@ -1160,10 +1160,10 @@ $ vi myFile.txt Using Admonitions To call attention to a statement, use an admonition. - Red Hat technical documentation currently uses Note, Important, and Warning admonitions. + Red Hat technical documentation currently uses Note, Important, and Warning admonitions. - Admonitions automatically include a suitable title according to the type of admonition. + Depending on the tools and workflow, admonitions might automatically include a suitable title according to the type of admonition. Do not use a phrase or anything else for the title. Keep the following considerations in mind if using admonitions: @@ -1181,20 +1181,20 @@ $ vi myFile.txt - Use a Note admonition to bring extra information to the user's attention. + Use a Note admonition to bring extra information to the user's attention. - Use an Important admonition to show the user a piece of information that should not be overlooked. + Use an Important admonition to show the user a piece of information that should not be overlooked. This information might not change anything that the user is doing, but it should show the user that this piece of information could be vital. - Use a Warning admonition to alert the reader to potential changes, such as files being removed, and not to perform the operation unless fully aware of the consequences. + Use a Warning admonition to alert the reader to potential changes, such as files being removed, and not to perform the operation unless fully aware of the consequences. diff --git a/en-US/E.xml b/en-US/E.xml index 343e765..6620c31 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -40,7 +40,7 @@ Emacs - If referring to the program, use "Emacs". For example, "Source-Navigator supports Emacs or vi commands". If referring to the shell prompt command, use "emacs". For example, "At the prompt, type emacs." The complete and correct name is "GNU Emacs". + If referring to the program, use "Emacs". For example, "Source-Navigator supports Emacs or vi commands". If referring to the shell prompt command, use "emacs". For example, "At the prompt, type emacs." The complete and correct name is "GNU Emacs". @@ -64,7 +64,7 @@ When referring to the keyboard key, use Enter. If referring to the keyboard key on Solaris, use Return. - When referring to typing a command, use "type" instead, such as "To open Source-Navigator from the command line, type snavigator." + When referring to typing a command, use "type" instead, such as "To open Source-Navigator from the command line, type snavigator." When typing information into a single-field dialog box, "enter" means "type and press Enter". An example is "enter the license number". For multi-field dialog boxes, see "type". diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 4457d31..70bec9b 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -759,7 +759,7 @@ - The fsck /dev/vdb1 command performs a file system check on the XFS file system residing on the /dev/vdb1 partition. + The fsck /dev/vdb1 command performs a file-system check on the XFS file system residing on the /dev/vdb1 partition. The fsck /dev/vdb1 command checks the XFS file system on the /dev/vdb1 partition. diff --git a/en-US/Language.xml b/en-US/Language.xml index f7f15ee..2fa11a2 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1644,7 +1644,7 @@ Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). - Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate goups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). + Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate groups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). See The Chicago Manual of Style, 17th Edition for detailed information on numbering formats. diff --git a/en-US/N.xml b/en-US/N.xml index ecac797..4feaff4 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -117,7 +117,7 @@ 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 ), or when writing exclusively for a European audience. + Otherwise, use "hash" to refer to a hashtag in social media, or to refer to Secure Hash Algorithm (see ), 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. diff --git a/en-US/New.xml b/en-US/New.xml index d35bcff..61c8f8d 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -41,7 +41,7 @@ Use "following" with a noun. - Avoid hyphenating with an "-ly" prefix: added an example. + Avoid hyphenating with an "-ly" suffix: added an example. If-Then statements. diff --git a/en-US/O.xml b/en-US/O.xml index 9cd08ac..80760ba 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -250,7 +250,7 @@ A phrase that was coined by the Red 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." + It is a reference to an "open source method", as in "The team developed this project the open source way." 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 Open Source Initiative, to avoid diluting the legal meaning of the term "open source". From 4a27046c2c04aeef60b5973db6ac8ee6d8dd29fd Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 5 Jul 2023 17:04:40 +0100 Subject: [PATCH 17/79] Updated IBM Style access info (#496) --- en-US/Resources.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en-US/Resources.xml b/en-US/Resources.xml index cf58ac1..d07160f 100644 --- a/en-US/Resources.xml +++ b/en-US/Resources.xml @@ -55,7 +55,7 @@ Red Hat employees can now access the latest version of the IBM Style Guide online, at https://www.ibm.com/docs/en/ibm-style/. - + From 513f64711a417ec96049869f7779b3ab1cfd6254 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Fri, 7 Jul 2023 09:50:23 +0100 Subject: [PATCH 18/79] Updated term entries (#497) --- en-US/A.xml | 4 ++-- en-US/Design.xml | 2 +- en-US/Grammar.xml | 2 +- en-US/K.xml | 2 +- en-US/O.xml | 11 +++++++++++ en-US/S.xml | 12 +++++++++++- en-US/T.xml | 10 ++++++++++ 7 files changed, 37 insertions(+), 6 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index 2897ced..bf3be12 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -256,7 +256,7 @@ - MaaS (Messaging-as-a-Service) + MaaS (Messaging-as-a-Service, Metal-as-a-Service) @@ -295,7 +295,7 @@ Hyphenate when written out: Thing-as-a-Service. For two-word prefixes, do not include a hyphen between the first and second words, for example: Mobile Backend-as-a-Service. - It can be used as an adjective to describe multiple: for example, when referring to IaaS, PaaS, and SaaS, use as-a-Service offerings, as-a-Service products, or similar wording. + It can be used as an adjective to describe multiple: for example, when referring to IaaS, MaaS, PaaS, and SaaS, use as-a-Service offerings, as-a-Service products, or similar wording. diff --git a/en-US/Design.xml b/en-US/Design.xml index 1caddc4..a44f92d 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -590,7 +590,7 @@ $ vi myFile.txt - As much as possible, leave the system-wide default as become: false or become: no and if a single task needs privileges, set become: true or become: yes on that task. + As much as possible, leave the systemwide default as become: false or become: no and if a single task needs privileges, set become: true or become: yes on that task. diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 70bec9b..2902861 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -865,7 +865,7 @@ Split contractions and abbreviations into separate paragraphs. --> Hyphenate Complex Adjectives - Hyphenate complex adjectives (compound modifiers). This is when two adjectives work together to modify an object. The hyphen is used when the first adjective modifies the second adjective. For example, cloud-based solutions, right-side paralysis, system-wide menu. + Hyphenate complex adjectives (compound modifiers). This is when two adjectives work together to modify an object. The hyphen is used when the first adjective modifies the second adjective. For example, cloud-based solutions, right-side paralysis, systemwide menu. diff --git a/en-US/K.xml b/en-US/K.xml index b6d9127..31efa55 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -103,7 +103,7 @@ key ring - n. Use the two-word form as a noun. For example, "add your new key to the key ring". + n. Use the two-word form as a noun. For example, "Verify that the Ceph client key ring is present in the /etc/ceph directory on the client node", or "add your new key to the key ring". adj. Use the hyphenated form as an adjective. For example, "copy the key-ring file to the server". diff --git a/en-US/O.xml b/en-US/O.xml index 80760ba..1278f07 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -279,6 +279,17 @@ + + OTP + + + n. OTP stands for "one-time password". + Always use lowercase for the phrase itself. Do not use any other variations. + + + + + output device diff --git a/en-US/S.xml b/en-US/S.xml index 20b92eb..12575ae 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -419,7 +419,7 @@ smart card - n. Do not use smartcard or smart-card. + adj., n. Always use the two-word form. Do not use "smart-card" or other variations. Do not capitalize unless it is part of a product name or other proper noun. @@ -547,6 +547,16 @@ a programming and technical sense, it also means "Run the source + + squad (n.) + + + Do not use to refer to a group that is formed to accomplish a task. Use "team" or "group" instead. + + + + + SR-IOV diff --git a/en-US/T.xml b/en-US/T.xml index 0bc0ea7..14c8b70 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -210,6 +210,16 @@ + + tribe (n.) + + + Do not use to refer to a group that is formed to accomplish a task. Use "team" or "group" instead. + + + + + troubleshoot (v.) From 4cd54926fde5caaf4d3d2395a0ccdf11f90bf26e Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Fri, 14 Jul 2023 11:52:30 +0100 Subject: [PATCH 19/79] Added guidance on omitting part of an output (#500) * Added guidance on omitting part of an output * Updated wording * Typo fix --- en-US/Design.xml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/en-US/Design.xml b/en-US/Design.xml index a44f92d..66aca59 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -475,6 +475,26 @@ $ vi myFile.txt --initial-dashboard-password=DASHBOARD_PASSWORD --dashboard-password-noupdate \ --allow-fqdn-hostname + + +
+ +
+ Omitting Part of Output + + 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. + Where output is not included, place a marker to show that information is purposely excluded. + When shortening the output, use a consistent notation. + Red{nbsp}Hat uses the ...output omitted... notation, starting and ending with an ellipsis, and highlighted in italics. + + +Notation for Excluding Part of Output +[student@workstation image]$ podman build --layers=false -t nexus . +STEP 1: FROM ubi8/ubi:8.3 +Getting image source signatures +...output omitted... +STEP 14: COMMIT ...output omitted... localhost/nexus:latest +
From 4a0e728118d9e4353b175f5f6073cb3bdd385c55 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Fri, 21 Jul 2023 17:41:37 +0100 Subject: [PATCH 20/79] Updated sample names and other small fixes (#502) --- en-US/Design.xml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 66aca59..0be13d6 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -250,7 +250,7 @@
- "POSIX recommends these conventions for command line arguments. [...] Arguments are options if they begin with a hyphen delimiter (‘-’). Multiple options may follow a hyphen delimiter in a single token if the options do not take arguments. Thus, ‘-abc’ is equivalent to ‘-a -b -c’. [...] Certain options require an argument. For example, the ‘-o’ option of the ‘ld’ command requires an argument—an output file name". and so on. + "POSIX recommends these conventions for command line arguments. [...] Arguments are options if they begin with a hyphen delimiter ('-'). Multiple options may follow a hyphen delimiter in a single token if the options do not take arguments. Thus, '-abc' is equivalent to '-a -b -c'. [...] Certain options require an argument. For example, the '-o' option of the 'ld' command requires an argument—an output file name". and so on. See info libc argument syntax for the full discussion. @@ -485,7 +485,7 @@ $ vi myFile.txt 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. Where output is not included, place a marker to show that information is purposely excluded. When shortening the output, use a consistent notation. - Red{nbsp}Hat uses the ...output omitted... notation, starting and ending with an ellipsis, and highlighted in italics. + Red Hat uses the ...output omitted... notation, starting and ending with an ellipsis, and highlighted in italics. Notation for Excluding Part of Output @@ -729,7 +729,8 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest - 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: Sunni Koning, Huong Sabo, and Jerlene Paluch. Sunni is a department manager and needs read access to the accounting directory. Huong is the lead accountant and needs both read and write access. + 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, Jerlene Paluch, Abby Quincy, Fricis Ritcher, and Jaya Lamont. + Huong is a department manager and needs read access to the accounting directory. Jerlene is the lead accountant and needs both read and write access. Choosing a Realistic Name From 02fcf95bd4b66da610d7be7215752c201c182ff3 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Fri, 4 Aug 2023 11:08:12 +0100 Subject: [PATCH 21/79] Various fixes (#512) --- en-US/Design.xml | 9 ++++----- en-US/Grammar.xml | 4 ++-- en-US/Language.xml | 2 +- en-US/P.xml | 2 +- en-US/Translation.xml | 18 ------------------ 5 files changed, 8 insertions(+), 27 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 0be13d6..3d4684c 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -16,7 +16,7 @@ Capitalization The standard for all Red Hat technical documentation is title case for all headings and titles. - Table headings, procedure headings, and formal paragraph titles fall under this heading; standard title case capitalization rules apply. + Table headings and procedure headings fall under this heading; standard title case capitalization rules apply. @@ -1277,13 +1277,12 @@ Book Title by First name Surname; Publisher. - For example, Maximum RPM by - + For example, Maximum RPM by Edward Bailey; Red Hat Press. + Referencing Other Internet Sites diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 2902861..3e66655 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -277,7 +277,7 @@ - If the restatement contains the word he, she, they, II, or we, then use who or whoever. "Do you think he would mind?" "Who do you think would mind?" "She's walking in the door." "Who's walking in the door?" + If the restatement contains the word he, she, they, I, or we, then use who or whoever. "Do you think he would mind?" "Who do you think would mind?" "She's walking in the door." "Who's walking in the door?" @@ -300,7 +300,7 @@ Sentence Length Try not to pack too much information into one sentence. - In technical documentation, try not to exceed 30 words in a sentence. + In technical documentation, try not to exceed 40 words in a sentence. Keep it short. The following sentence is a bad writing example: diff --git a/en-US/Language.xml b/en-US/Language.xml index 2fa11a2..c7fc7c1 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -704,7 +704,7 @@ shoot yourself in the foot - To "shoot yourself in the foot" indicates that you did something to harm your own cause, or acting against your own best interests. Remove the sentence; it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes".) + To "shoot yourself in the foot" indicates that you did something to harm your own cause, or acting against your own best interests. Remove the sentence; it should be self-evident from the surrounding information. diff --git a/en-US/P.xml b/en-US/P.xml index d1e5df7..92f8b79 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -15,7 +15,7 @@ Marketing, Brand, Customer Portal Usage - For all-caps text, such as banners, use "<VARIANT>-ASERVICE" for the spelled-out version. The same abbreviation is used across all groups. + For all-caps text, such as banners, use "<VARIANT>-AS-A-SERVICE" for the spelled-out version. The same abbreviation is used across all groups. diff --git a/en-US/Translation.xml b/en-US/Translation.xml index e604ce1..2cd19b1 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -272,27 +272,18 @@ To obtain the file name of the default kernel with the grubby command: - - ... - Finding the index number of the default kernel: - - ... - Use the grubby command to persistently change the default kernel: - - ... - @@ -304,27 +295,18 @@ Obtain the file name of the default kernel with the grubby command: - - ... - Find the index number of the default kernel: - - ... - Use the grubby command to persistently change the default kernel: - - ... - From 7ccd2bd18fc367736e555692aaa8512f3d059acf Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Fri, 4 Aug 2023 17:33:14 +0100 Subject: [PATCH 22/79] Implementing various feedback suggestions from Rachel (#513) * Implementing various feedback suggestions from Rachel * Addressed review comments * Addressed further review comment --- en-US/Cross_references.xml | 8 ++--- en-US/Design.xml | 69 ++++++++++++++++++++++++------------- en-US/Language.xml | 70 +++++++++++++++++++------------------- 3 files changed, 85 insertions(+), 62 deletions(-) diff --git a/en-US/Cross_references.xml b/en-US/Cross_references.xml index 5468451..aba9f6b 100644 --- a/en-US/Cross_references.xml +++ b/en-US/Cross_references.xml @@ -40,15 +40,15 @@
- The Repeatability Test + Repetition - Must the information be repeated? + Repetition is a useful tool for reinforcing new knowledge and skills, emphasizing important ideas, and providing readers with important information at their point of need. - This is a hard question, and one that many authors abhor. Often the answer is yes. If the information is vital, and must appear in multiple places, then it must be repeated. In some circumstances, such is in online help, the reader wants the answer immediately. Do not force even one extra click on them. In a safety situation, it might be the only chance for the reader to find critical information quickly. Any vital information, which is not more than a couple of paragraphs (or half a page, or five rows of a table), can be repeated rather than be cross-referenced to. + Repeating necessary information also saves the reader time and effort. In some circumstances, such as when using online help, the reader is trying to answer an immediate question or to solve a problem. In a safety situation, it is important for the reader to find critical information quickly. - Cross-referencing is a good servant but a poor master. Content still rules! + If the information is vital, and must appear in multiple places, then it must be repeated. Any vital information, which is not more than a couple of paragraphs (or half a page, or five rows of a table), can be repeated rather than be cross-referenced to.
diff --git a/en-US/Design.xml b/en-US/Design.xml index 3d4684c..ceb68ec 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -923,11 +923,11 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest
- Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly + Abbreviations, Acronyms, Initialisms, and Special Characters - This section describes how to use abbreviations, acronyms, and initialisms correctly in Red Hat documentation. + This section defines abbreviations, acronyms, initialisms, and special characters. - + Abbreviations An abbreviation is a shortened form of a word or phrase. For example, Pty. and Inc. are abbreviations for "proprietary" and "incorporated", respectively. Read them as the word for which they are an abbreviation. @@ -937,46 +937,68 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest Acronyms - What are acronyms anyway? - They are similar to abbreviations and initialisms but they are pronounced as a word. - An acronym is a word that is formed from the initial letters of a name, such as ROM for Read-Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. - COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol. + An acronym is a word that is formed from the initial letters of a name, such as ROM for Read-Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. + COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol. + + + + + Initialisms + + An initialism is an abbreviation that consists of the first letters of words in a phrase, syllables, or some combination thereof. Each character is pronounced separately. For example, FTP is an initialism for File Transfer Protocol. + + Special Characters + + For the purposes of this guide, special characters refer to those characters that are listed in . + This section addresses how to use special characters as part of a file or directory name, such as "the .bashrc file" and "the _build/ directory". + + + +
+ Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly - Consider pronunciation when using articles. For example, use "an RTS (real-time strategy)", because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade", because RAM is an acronym and you pronounce it as a word (răm). + This section describes how to use abbreviations, acronyms, initialisms, and special characters correctly in Red Hat documentation. + + First Mentions Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ...". - Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)". - Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML. + Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML. + + + Capitalization - To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes. + 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"); see the IBM Style Guide or another suitable reference if you are unsure. + + + Articles - Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see the IBM Style Guide or another suitable reference if you are unsure. + When deciding which articles to use, consider pronunciation. + For example, use "an RTS (real-time strategy)", because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade", because RAM is an acronym and you pronounce it as a word (răm). - - - Initialisms - - An initialism is an abbreviation that consists of the first letters of words in a phrase, syllables, or some combination thereof. Each character is pronounced separately. For example, FTP is an initialism for File Transfer Protocol. - - + + + Plurals - Consider pronunciation when using articles. See for more information. + To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes. + + Special Characters - - Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article. - + + Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article. + @@ -990,6 +1012,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest Using "a -compile/ directory" is correct, because you pronounce "a dash compile directory". +
diff --git a/en-US/Language.xml b/en-US/Language.xml index c7fc7c1..6370179 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1092,13 +1092,16 @@ Avoiding Ambiguities - - Capitalizing Proper Nouns + + Avoid May and Should - In some cases it is not clear if a term refers to a concept or a proper noun or product name. - By using the correct capitalization, you help translators identify untranslatable proper nouns and Red Hat product names. + The verb "may" might indicate possibility or grant permission. + Similarly, "should" might imply a recommendation or express obligation or expectation. + A sentence containing one of these verbs often has a double meaning. + Avoid these types of words. + @@ -1114,8 +1117,27 @@ - This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. - This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode. + The next() method should return null to indicate the end of results. + + + The next() method is expected to return null to indicate the end of results. + + + Or: The next() method must return null to indicate the end of results. + + + + + + It may be held in memory. + + + It can be held in memory. + + + Or: It might be held in memory. + + @@ -1127,7 +1149,7 @@ - + Avoid Stating that Something Is Easy @@ -1172,16 +1194,13 @@ - - Homographic Verbs + + Capitalizing Proper Nouns - The verb "may" might indicate possibility or grant permission. - Similarly, "should" might imply a recommendation or express obligation or expectation. - A sentence containing one of these verbs often has a double meaning. - Avoid these types of words. + In some cases it is not clear if a term refers to a concept or a proper noun or product name. + By using the correct capitalization, you help translators identify untranslatable proper nouns and Red Hat product names. -
@@ -1197,27 +1216,8 @@ - The next() method should return null to indicate the end of results. - - - The next() method is expected to return null to indicate the end of results. - - - Or: The next() method must return null to indicate the end of results. - - - - - - It may be held in memory. - - - It can be held in memory. - - - Or: It might be held in memory. - - + This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. + This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode. From 91d9a951cf40dda7346560548796cc84988e8918 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Tue, 8 Aug 2023 15:35:10 +0100 Subject: [PATCH 23/79] Added more punctuation guidance (#515) * Added more punctuation guidance * Implemented review feedback --- en-US/Punctuation.xml | 113 ++++++++++++++++++++++++++++++++++-------- en-US/Translation.xml | 100 +++++++++++++++++++++++++++++++++++++ 2 files changed, 192 insertions(+), 21 deletions(-) diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 4e0020a..fb58491 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -54,9 +54,9 @@ Try to limit your use of colons and semicolons. Separate sentences with a period if possible. - To introduce a list or series: + To introduce a series: - A colon is generally used before a list or series. + A colon is generally used before a series. @@ -70,7 +70,7 @@ - Do not use a colon if the list is a complement or object of an element in the sentence. + Do not use a colon if the series is a complement or object of an element in the sentence. @@ -79,7 +79,7 @@ - + + + + + + Use a semicolon to separate items in a series if the items contain commas. + + + + + Every day I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner. + - Use a colon after "as follows" and "the following" if the related list immediately follows the stem, or introductory sentence. + When a conjunctive adverb (such as however, therefore, otherwise, namely, for example, and so on) joins two independent clauses, use a semicolon before the conjunctive adverb and a comma after it. + + + + + + I think; therefore, I am. + + + + + + + + To introduce a list, command, code block, or procedure + + If a list, command, code block, or procedure immediately follows a single stem or introductory sentence, then end that sentence with a colon. + + + + If, however, any sentences intervene between the introduction and the next item, then end both the introduction and any intervening sentences with a period instead. + + + + In the following example, the related list immediately follows the stem, or introductory sentence, after "as follows". + If that sentence instead ends with "the following", then ensure that a noun is used after those words. @@ -142,7 +180,7 @@ - Use a colon to introduce a bullet list. + In the following example, a colon is used to introduce a bullet list: @@ -176,7 +214,7 @@ - Cost per + Cost per unit @@ -185,32 +223,43 @@ - - - Use a semicolon to separate items in a series if the items contain commas. + + + + In the following example, a colon is used for a step that introduces a command: - + - Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner. + 2. Use the ansible-navigator run command to run the allfacts.yml playbook: +[student@workstation manage-facts]$ ansible-navigator run allfacts.yml +PLAY [Gather and display facts for managed nodes] **************************** - - - Use a semicolon before a conjunctive adverb, such as however, therefore, otherwise, namely, for example, and so on. - + - + + In the following example, several sentences introduce a code example, and each one ends in a period: + + - I think; therefore, I am. + To configure SELinux persistently, use the /etc/selinux/config file. + In the following default example, the configuration sets SELinux to mode. + The comments list other valid values, such as the and modes. +# This file controls the state of SELinux on the system. +# SELINUX= can take one of these three values: +# enforcing - SELinux security policy is enforced. +# permissive - SELinux prints warnings instead of enforcing. +# disabled - No SELinux policy is loaded. +...output omitted... - +
@@ -269,6 +318,28 @@ + + + With conjunctive adverbs: + + When using a conjunctive adverb (such as however, therefore, otherwise, namely, for example, and so on) in a sentence, set it off with commas. + + + + + + + It rained all afternoon. As a result, we canceled our picnic. + + + + + + The grass, however, stayed dry under the trees. + + + + In adverbial clauses and phrases: diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 2cd19b1..9801c5e 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -321,6 +321,102 @@
+
+ +
Punctuation in Lists + + For each item in a list, start with either a complete sentence or a sentence fragment. + + + For a list where all items are complete sentences, end each item with a period. + + + Example: + + + Which statement is true about deployments and deployment configurations? + + + + + Deployments use replica sets, and deployment configurations use replication controllers. + + + + + Deployments use replication controllers, and deployment configurations use replica sets. + + + + + Deployments and deployment configurations both refer to the same thing. + + + + + Deployments use replica sets, and deployment configurations use stateful sets. + + + + + For a list where all items are sentence fragments, do not end the items with any punctuation. + + + Example: + + + Which resource type does the Operator Lifecycle Manager use to store information about installed operators? + + + + + Operator group + + + + + Catalog source + + + + + Install plan + + + + + Operator + + + + + For a list where the items start with sentence fragments, and any of those fragments are followed by a complete sentence, end each of the fragments and sentences with a period. + + + Example: + + + + + Identifier of the object schema version. + + + + + Schema identifier. In this example, the object conforms to the pod schema. + + + + + Name of the container inside a pod. + Container names are important for oc commands when a pod contains multiple containers. + + + + + For information about punctuation in lead-in sentences that introduce a list, see . + +
@@ -510,6 +606,10 @@ Usage: rhevm-iso-uploader [options] list rhevm-iso-uploader [options] upload [file1] [file2] [file3] + + For information about punctuation in lead-in sentences that introduce a code block, see . + +
Entities From bc18591a17b17cefc18f99b0ef87b728002078f9 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Tue, 15 Aug 2023 14:58:06 +0100 Subject: [PATCH 24/79] Updated audience description (#518) * Updated audience description * Further updated audience wording --- en-US/Audience.xml | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/en-US/Audience.xml b/en-US/Audience.xml index 165da34..4e63d5f 100644 --- a/en-US/Audience.xml +++ b/en-US/Audience.xml @@ -6,11 +6,18 @@
Audience - This guide is the official style guide for technical documentation for Red Hat training and certification content, including how to write for global audiences and translation, common mistakes to avoid, rules for everyday punctuation, and grammar. + This guide is the official style guide for Red Hat training and certification content, and for all other technical documentation except as stated. + Red Hat product documentation by Customer Content Services (CCS) follows the Red Hat supplementary style guide at instead of this Red Hat Technical Writing Style Guide. - Other Red Hat technical documentation, including product documentation by Customer Content Services (CCS), follows the Red Hat supplementary style guide for product documentation at instead of this Red Hat Technical Writing Style Guide. + The Red Hat Technical Writing Style Guide includes everyday punctuation and grammar, common mistakes to avoid, strategies for translation and global audiences, and a word usage dictionary. + + This guide is a public guide. It is reviewed and maintained by Red Hat. Contributions from the wider community are always welcomed. + + + Other resources for technical writing are listed in . +
From b6dba5ad02434af2ad1342b02438f0f7ad485d79 Mon Sep 17 00:00:00 2001 From: Christine Belzie <105683440+CBID2@users.noreply.github.com> Date: Wed, 16 Aug 2023 04:15:35 -0400 Subject: [PATCH 25/79] Adding information about posessives (#519) * feat: added section about posessives * feat: here's the actual section * fix: made some revisions * Content and formatting updates * Update en-US/Punctuation.xml Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * fix: made some revisions * fix: made another revision * Removed company name and restructured section * added link in section 3.6 * Final XML fix --------- Co-authored-by: Julian Cable Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> --- en-US/Design.xml | 17 ++++++-- en-US/Grammar.xml | 90 ++++++++++++++++++++++++++++++++++++++++++- en-US/Punctuation.xml | 4 ++ 3 files changed, 106 insertions(+), 5 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index ceb68ec..d1cf53d 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -156,10 +156,6 @@ Click the ^ symbol. - - If you cannot easily reproduce the symbol, include a screen capture, or a succinct description of the object type, or both. - Use this approach for icons, especially when they have no tooltip or other help text. - Preferred Style for Documenting Icons Click the Upload ( @@ -994,6 +990,14 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest + + Possessives + + Do not use possessives with abbreviations. For examples and more information, see . + + + + Special Characters @@ -1058,6 +1062,11 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest + + Do not use possessives to refer to product names. + For examples and more information, see . + + Do not hyphenate or break a product name across lines. diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 3e66655..79bdd98 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -146,6 +146,95 @@
+
+ Possessives + + A possessive indicates that something or someone belongs to a person or thing. + + + For guidance on how to form a possessive, see . + + + Do not use possessives with product names. + + + + + + + + + + Example + Improvement + + + + + + + Red Hat OpenShift's Logging operator creates cluster logging and cluster log forwarder instances. + The Red Hat OpenShift Logging operator creates cluster logging and cluster log forwarder instances. + + + + OpenSauced's Chrome Extension is a good tool to display your open source contributions. + The OpenSauced Chrome Extension is a good tool to display your open source contributions. + + + + + + +
+ + + Do not use possessives with abbreviations. + + + + + + + + + Example + Improvement + + + + + + + You can find NASA's documentation on GitHub. + You can find NASA documentation on GitHub. + + + + + + +
+ + + Otherwise, you can use possessives for people and inanimate objects. + + + Examples: + + + + + Eddie Jaoude's YouTube channel is one of the best sources for learning how to use GitHub. + + + + + The alt tag's text for the Pepsi logo is too short. + + + +
Using Who, Whom, That, and Which Correctly @@ -285,7 +374,6 @@ -
Sentence Structure diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index fb58491..bb65489 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -610,6 +610,10 @@ PLAY [Gather and display facts for managed nodes] **************************** Singular proper names ending in s only need an apostrophe (for example, Dickens' novels). + + For guidance on whether to use a possessive, see . + +
From 267f8c9f3afe393c12aaa9aba6bbbf36047908cb Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Wed, 16 Aug 2023 18:26:34 +0100 Subject: [PATCH 26/79] Updated view and edit files section --- en-US/Design.xml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index d1cf53d..f9acd84 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -636,7 +636,9 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest If the file to edit is empty or does not exist, do not highlight any content to add. - You can also use here documents to describe how to create a file with required content. The syntax of here documents varies by system, shell, language, and so on. The following example creates the my-script file in the current directory, with the example content. + You can also use here documents to describe how to create a file with required content. + For more information about here documents, see + The syntax of here documents varies by system, shell, language, and so on. The following example creates the my-script file in the current directory, with the example content. my-script @@ -649,6 +651,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest
+
Using Host and Usernames Correctly From 0720e2c40cd90cdebe538f1e5dbc07c6abc7f506 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Tue, 22 Aug 2023 13:18:07 +0100 Subject: [PATCH 27/79] Added release notes for 6.1 and updated version information (#522) --- en-US/Book_Info.xml | 4 +- en-US/Design.xml | 4 +- en-US/New.xml | 76 ++++++++++++++++++- ...le_Conventions_for_Writers_and_Editors.ent | 4 +- 4 files changed, 81 insertions(+), 7 deletions(-) diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index 163cbb2..e49ea58 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -8,11 +8,11 @@ Red Hat Technical Writing Style Guide - 6.0 + 6.1 1 - The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat. It is intended as a supplement to the titles listed in + The Red Hat Technical Writing Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat. It is intended as a supplement to the titles listed in diff --git a/en-US/Design.xml b/en-US/Design.xml index f9acd84..6414394 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -386,7 +386,7 @@ -
+
Documenting Multiple or Long Commands @@ -475,7 +475,7 @@ $ vi myFile.txt
-
+
Omitting Part of Output 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. diff --git a/en-US/New.xml b/en-US/New.xml index 61c8f8d..4f665e9 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -5,6 +5,81 @@ ]>
New in This Release + + Release 6.1 + Update in August 2023 to provide added or updated guidance and to address reported issues. + The listed items here now include links to the appropriate sections. + + + + Updated audience information for this guide. + See . + + + Updated guidance about writing titles. + See . + + + Updated guidance on continuation prompts. + See . + + + Updated using realistic usernames. + See . + + + Added guidance on omitting part of an output. + See . + + + Added guidance about possessives with product names and abbreviations. + See . + + + Various additions to the Punctuation section. + See . + + + Restructured "Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly". + See . + + + Rewrote "The Repeatability Test" section and renamed it to "Repetition". + See . + + + Changed "Homographic Verbs" subsection title to "Avoid May and Should". + See . + + + Inclusive naming of default branch. + See . + + + Updated IBM Style access information. + See . + + + Adjusted sentence length guideline. + See . + + + Removed some references that were specific to DocBook. + + + Use "team" or "group" instead of "squad". + See . + + + New or updated usage entries: application velocity, key ring, Metal-as-a-Service, OTP, smart card, systemwide, virtualized. + See . + + + Various other fixes. + + + + Release 6.0 Major update in December 2022 to add further style and grammar guidance: @@ -109,7 +184,6 @@ - Release 5.1 Minor update in January 2022 to address some reported issues: diff --git a/en-US/Style_Conventions_for_Writers_and_Editors.ent b/en-US/Style_Conventions_for_Writers_and_Editors.ent index a9587a6..c062671 100644 --- a/en-US/Style_Conventions_for_Writers_and_Editors.ent +++ b/en-US/Style_Conventions_for_Writers_and_Editors.ent @@ -1,5 +1,5 @@ - + - \ No newline at end of file + \ No newline at end of file From f6a12a64c077783ac34e171630be1342639604c6 Mon Sep 17 00:00:00 2001 From: Harpal Singh <52556240+harpasin@users.noreply.github.com> Date: Wed, 23 Aug 2023 16:14:20 +0530 Subject: [PATCH 28/79] updating homepage (#525) --- css/style.css | 7 ++++--- index.html | 49 +++++++++++++++++++++++-------------------------- 2 files changed, 27 insertions(+), 29 deletions(-) diff --git a/css/style.css b/css/style.css index 3e0338d..8807fbb 100644 --- a/css/style.css +++ b/css/style.css @@ -9,7 +9,7 @@ } body { - font-family: 'overpass',sans; + font-family: "liberation sans", "Myriad ", "Bitstream Vera Sans", "Lucida Grande", "Luxi Sans", "Trebuchet MS", helvetica, verdana, arial, sans-serif; background-color: #fff; margin: 0; padding: 0; @@ -44,7 +44,7 @@ header img { } #main > div { - padding-top: 5%; + padding-top: 2%; } #main > img { @@ -52,7 +52,8 @@ header img { } #main p { - width: 50%; + text-align: left; + width: 70%; font-size: 1.33em; margin: auto; } diff --git a/index.html b/index.html index c03c6a3..22cb2b9 100644 --- a/index.html +++ b/index.html @@ -40,43 +40,40 @@
-

- The official style guide for Red Hat technical documentation, including how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and much more. -

- -

- - Red Hat Technical Writing Style Guide v6.0 -

- - Red Hat Technical Writing Style Guide v5.1 -

- -

- - Red Hat Brand Standards -

- -
+ + Red Hat Technical Writing Style Guide v6.1 + +

+ + Red Hat Brand Standards +

+

+
+ This guide is the official style guide for Red Hat training and certification content, and for all other technical documentation except as stated. + Red Hat product documentation by Customer Content Services (CCS) follows the Red Hat supplementary style guide instead of this Red Hat Technical Writing Style Guide. +

+
+

+ The Red Hat Technical Writing Style Guide includes everyday punctuation and grammar, common mistakes to avoid, strategies for translation and global audiences, and a word usage dictionary. +

+
+

+ This guide is a public guide. It is reviewed and maintained by Red Hat. Contributions from the wider community are always welcomed. +

+
-

Copyright ©2022 Red Hat

+

Copyright ©2023 Red Hat

-

Powered by HTML5

+

Powered by HTML5

From be390161c28cde4e7ea8e908adb43db10577e259 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:50:12 +0000 Subject: [PATCH 29/79] 6.2 quick fixes (#544) --- en-US/Language.xml | 13 ------------- en-US/Punctuation.xml | 2 +- en-US/V.xml | 2 +- 3 files changed, 2 insertions(+), 15 deletions(-) diff --git a/en-US/Language.xml b/en-US/Language.xml index 6370179..967133d 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -213,19 +213,6 @@ - - check this site - - - Understood to mean "have a look at this website". - The preferred phraseology is "See www.somewhere.com for more information." - It is better to avoid "check" because it has so many meanings. - - - - - - core competency diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index bb65489..2b3658d 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -634,7 +634,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - For another character, use its name followed by the symbol in parentheses. + For all other characters, use the character name followed by the symbol in parentheses. Do not use the symbol on its own. diff --git a/en-US/V.xml b/en-US/V.xml index e6ae9b1..5cefe1a 100644 --- a/en-US/V.xml +++ b/en-US/V.xml @@ -78,7 +78,7 @@ - + virtual, virtualized From 9daece9d7b5d362077aed7a8ee25bb94cd5e4c0e Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Tue, 21 Nov 2023 16:56:45 +0000 Subject: [PATCH 30/79] Some updates concerning punctuation (#545) * Updated guidance for punctuation and special characters * Enhanced guidance about punctuation in lists * Minor formatting * Content and formatting * Applied feedback * Minor fixes --- en-US/Design.xml | 10 +-- en-US/Grammar.xml | 19 ++++++ en-US/Punctuation.xml | 144 ++++++++++++++++++++++++++++++++++++++++-- en-US/Translation.xml | 78 +++++++++++++++++++---- 4 files changed, 229 insertions(+), 22 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 6414394..8e6b7d7 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -133,7 +133,7 @@ Depending on the context, an option might be to write around an incorrectly spelled interface item rather than naming it specifically.
- User Interface Elements, Punctuation, and Symbols + User Interface Elements and Punctuation When describing UI elements, do not include punctuation that appears on those elements, unless omission of that punctuation might lead to confusion. @@ -146,16 +146,16 @@ In some cases it is preferred practice to include the object type for the sake of clarity. - Consider the following: + Consider the following example: - Preferred Style for Documenting Symbols and Other Special Characters + Preferred Style for Documenting Icons Click the Upload ( @@ -296,7 +296,7 @@ Source options [username@]hostname:/repository_filename) - The optional username, indicated by brackets ([]), followed by the hostname and path to the repository. + The optional username, indicated by brackets, [], followed by the hostname and path to the repository. All aspects of this component must be replaced with valid values. diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 79bdd98..50fa863 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -215,6 +215,25 @@ + + + You can use the possessive form with the "Red Hat" company name to refer only to the company itself, without identifying any products or services. + + + Examples: + + + + + Use the "DEI" term to refer to Red Hat's diversity, equity, and inclusion efforts and teams. + + + + + Red Hat's approach to hybrid cloud security helps customers implement security across their entire infrastructure. + + + Otherwise, you can use possessives for people and inanimate objects. diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 2b3658d..2b29564 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -625,19 +625,141 @@ PLAY [Gather and display facts for managed nodes] **************************** +
+ Punctuation in Lists + + For information about punctuation in lists, refer to . + + +
+ +
+ Punctuation in Tables + + Use the following guidance for punctuation in tables: + + + If all cells in a table column are complete sentences, then end each cell with a period. + + + If all cells in a table column are sentence fragments, then do not use a period to end each cell. + + + If cells in a table column contain a mixture of complete sentences and sentence fragments, then first consider whether it would be appropriate to make them grammatically parallel (either all complete sentences or all sentence fragments). + However, in some cases, such an approach might not work, where tables are complex and include a variety of content, such as lists of strings, variables, IP addresses, descriptions, or states (selected or cleared). + In such cases, treat each cell as an individual entry, and either use or omit a closing period depending on whether that cell is a complete sentence. + + + Example of a complex table with punctuation: + + + + + + + + + Field + Value + + + + + + + + Question + + + Default domain name + + + + + + Description + + + This domain name is used to set the hostname of the node. + + + + + + Answer variable name + + + global_domain_name + + + + + + Answer type + + + text + + + + + + Required + + + (selected) + + + + + + Minimum length + + + 1 + + + + + + Maximum length + + + 251 + + + + + + Default answer + + + lab.example.com + + + + + +
+ +
+
- Referring to Punctuation Marks + Referring to Punctuation Marks and Special Characters - To refer to a punctuation mark or special character, use its name alone if it is one of the following standard characters: + To refer to a punctuation mark or special character, use its name alone if it is one of the following standard characters: . , : ; ' " ( ) [ ] { } ! ? - For all other characters, use the character name followed by the symbol in parentheses. + For all other characters, use the character name followed by the symbol in parentheses. + For special character names that include a noun such as "sign", "symbol", or "character", provide the character name, the noun that describes the symbol, and then the symbol in parentheses, for example "the greater than symbol (>)". + For special character names that do not include such nouns, provide the character name and the symbol in parentheses, for example "a forward slash (/)". + You can end a sentence with the symbol in parentheses. - Do not use the symbol on its own. + Do not use the symbol on its own. Referring to Punctuation Marks @@ -647,9 +769,21 @@ PLAY [Gather and display facts for managed nodes] **************************** The path contains the library qualifier in braces. + + Referring to Special Characters + + + When a regular user starts a shell, the prompt includes an ending dollar character ($). + + + Use the pipe character (|) to send the output of one program to the input of another program. + + + The hyphen after the greater than symbol (>) indicates that a newline character (\n) is not added to the end of the variable. + - For more details, see the IBM Style Guide. + For more details, see the IBM Style Guide.
diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 9801c5e..9d0220e 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -323,10 +323,14 @@
-
Punctuation in Lists +
Punctuation in Lists For each item in a list, start with either a complete sentence or a sentence fragment. + + A complete sentence must include a subject and a verb. + It conveys a complete thought, and can stand on its own. + For a list where all items are complete sentences, end each item with a period. @@ -334,12 +338,12 @@ Example: - Which statement is true about deployments and deployment configurations? + Which statement is true about deployments and deployment configurations? - Deployments use replica sets, and deployment configurations use replication controllers. + Deployments use replica sets, and deployment configurations use replication controllers. @@ -354,7 +358,7 @@ - Deployments use replica sets, and deployment configurations use stateful sets. + Deployments use replica sets, and deployment configurations use stateful sets. @@ -365,27 +369,77 @@ Example: - Which resource type does the Operator Lifecycle Manager use to store information about installed operators? + Kubernetes networking provides the following capabilities: + + + + + Highly coupled container-to-container communications + + + + + Pod-to-pod communications + + + + + Pod-to-service communications + + + + + External-to-service communications + + + + + Sometimes, list items might include some form of a verb, but if they do not also include a subject, then they are not capable of standing on their own. + Such items count as sentence fragments, and are not ended with any punctuation. + + + Example: + + + Common uses for jobs include the following tasks: - Operator group + Initializing or migrating a database - Catalog source + Calculating one-off metrics from information within the cluster + + + + + Creating or restoring from a data backup + + + + + Example: + + + Consider the following settings when creating a route: + + + + + An optional path, for path-based routes - Install plan + A target port that the application listens to - Operator + An encryption strategy, depending on whether you need a secure or an insecure route @@ -398,18 +452,18 @@ - Identifier of the object schema version. + Identifier of the object schema version. - Schema identifier. In this example, the object conforms to the pod schema. + Schema identifier. In this example, the object conforms to the pod schema. Name of the container inside a pod. - Container names are important for oc commands when a pod contains multiple containers. + Container names are important for oc commands when a pod contains multiple containers. From a353d5e4c51f7e3365e44fb72dd5aa611882c307 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Thu, 23 Nov 2023 15:22:44 +0000 Subject: [PATCH 31/79] Word usage updates: screenshot, lookup, see/refer to (#546) * Word usage updates: screenshot, lookup, see/refer to * Addresses one comment * Updates to see/refer to entries * Minor fix --- en-US/0-9.xml | 2 +- en-US/A.xml | 12 ++++++------ en-US/B.xml | 18 +++++++++--------- en-US/C.xml | 20 ++++++++++---------- en-US/D.xml | 10 +++++----- en-US/Design.xml | 26 +++++++++++++------------- en-US/E.xml | 6 +++--- en-US/F.xml | 14 +++++++------- en-US/G.xml | 4 ++-- en-US/Grammar.xml | 4 ++-- en-US/H.xml | 10 +++++----- en-US/I.xml | 10 +++++----- en-US/K.xml | 6 +++--- en-US/L.xml | 11 ++++------- en-US/Language.xml | 10 +++++----- en-US/M.xml | 2 +- en-US/N.xml | 2 +- en-US/New.xml | 30 +++++++++++++++--------------- en-US/O.xml | 10 +++++----- en-US/P.xml | 8 ++++---- en-US/Punctuation.xml | 6 +++--- en-US/R.xml | 7 ++++--- en-US/S.xml | 41 +++++++++++++++++++++++------------------ en-US/T.xml | 16 ++++++++-------- en-US/Translation.xml | 8 ++++---- en-US/U.xml | 8 ++++---- en-US/V.xml | 2 +- en-US/WUG_Intro.xml | 2 +- en-US/XYZ.xml | 2 +- 29 files changed, 155 insertions(+), 152 deletions(-) diff --git a/en-US/0-9.xml b/en-US/0-9.xml index 1ad984c..76d5120 100644 --- a/en-US/0-9.xml +++ b/en-US/0-9.xml @@ -21,7 +21,7 @@ 2-track (IT) - adj. A less common way to refer to bimodal or hybrid IT. See . + adj. A less common way to refer to bimodal or hybrid IT. Refer to . diff --git a/en-US/A.xml b/en-US/A.xml index bf3be12..af66767 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -69,7 +69,7 @@ v. "Alternate" as a verb means to change between two states or options. - See also . + Refer also to . @@ -84,7 +84,7 @@ "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something", use "an alternative method is to ...". - See also . + Refer also to . @@ -97,7 +97,7 @@ For times of day, use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". - See also . + Refer also to . @@ -114,14 +114,14 @@ When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. - See also . + Refer also to . - The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . + The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, refer to the AMD Trademark Information page at . - For more information about Intel® trademarks, see and . + For more information about Intel® trademarks, refer to and . diff --git a/en-US/B.xml b/en-US/B.xml index ed2bc30..af67e4c 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -19,7 +19,7 @@ Use the one-word form only if it is part of the established product terminology, for example "Mobile Backend-as-a-Service", and when it is not being used to describe a generic process. - See also + Refer also to @@ -73,7 +73,7 @@ backwards compatible - Do not use. Instead, use "compatible with earlier versions" to refer to something that is compatible with older equipment or previous versions of software. See also . + Do not use. Instead, use "compatible with earlier versions" to refer to something that is compatible with older equipment or previous versions of software. Refer also to . @@ -106,7 +106,7 @@ basically - Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." See also . + Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." Refer also to . @@ -152,7 +152,7 @@ big data - n., adj. Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. See also . Big data is also never hyphenated, per AP style, even when used as a complex adjective. + n., adj. Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. Refer also to . Big data is also never hyphenated, per AP style, even when used as a complex adjective. @@ -296,7 +296,7 @@ Bps, bps - The abbreviation of bytes per second is Bps. The abbreviation of bits per second is bps. To avoid confusion, do not use at the beginning of a sentence. See also . + The abbreviation of bytes per second is Bps. The abbreviation of bits per second is bps. To avoid confusion, do not use at the beginning of a sentence. Refer also to . @@ -306,7 +306,7 @@ breadcrumb trail - See the IBM Style Guide for initial guidance on how to use this term. + Refer to the IBM Style Guide for initial guidance on how to use this term. @@ -379,10 +379,10 @@ A copy-on-write file system for Linux. Use an uppercase "B" when referring to the file system. When referring to tools, commands, and other utilities that relate to the file system, be faithful to those utilities. - See for more information on this file system. + Refer to for more information on this file system. - See for a list of file-system names and how to present them. + Refer to for a list of file-system names and how to present them. @@ -428,7 +428,7 @@ Ordinarily you would not include the text "button" in a procedure or description. For example, "Click OK to continue" is perfectly acceptable. It might be necessary to distinguish between buttons and links; for example, "Click the Download link". - See also . + Refer also to . diff --git a/en-US/C.xml b/en-US/C.xml index a627a7b..7503cd0 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -46,7 +46,7 @@ When referring to a compact disk, use "CD". For example, "Insert the CD into the CD drive". The plural is "CDs". - See the Word Usage chapter of the IBM Style Guide for more information. + Refer to the Word Usage chapter of the IBM Style Guide for more information. @@ -67,7 +67,7 @@ Correct. Ceph is a distributed storage platform that provides object, block, and file storage. - See + Refer to Do not use alternative capitalization. @@ -129,7 +129,7 @@ Define on first use; generally continuous integration/continuous delivery. It does not mean continuous development, a term with questionable usefulness and only marginal adoption. - See also , , . + Refer also to , , . @@ -153,7 +153,7 @@ - See the Word Usage chapter of the IBM Style Guide for more information. + Refer to the Word Usage chapter of the IBM Style Guide for more information. @@ -186,7 +186,7 @@ cloud - Although cloud is important to Red Hat's business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase "c" when referring to cloud or cloud computing in a general sense. Use a capitalized "C" when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. See also "big data". + Although cloud is important to Red Hat's business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase "c" when referring to cloud or cloud computing in a general sense. Use a capitalized "C" when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. Refer also to "big data". @@ -247,7 +247,7 @@ combo-box - Do not use as an abbreviation for "combination box". See the relevant entry in the IBM Style Guide for further usage information. + Do not use as an abbreviation for "combination box". Refer to the relevant entry in the IBM Style Guide for further usage information. @@ -313,7 +313,7 @@ command line, command prompt, command-line - See the appropriate entries in the IBM Style Guide for an explanation of how to use these terms. + Refer to the appropriate entries in the IBM Style Guide for an explanation of how to use these terms. @@ -348,7 +348,7 @@ communication service provider (CSP) - Another way to refer to a telecommunications provider. See also . + Another way to refer to a telecommunications provider. Refer also to . @@ -358,7 +358,7 @@ Containers-as-a-Service - The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. See also . + The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. Refer also to . @@ -511,7 +511,7 @@ n. CVE stands for Common Vulnerabilities and Exposures, and should be capitalized as shown. - See for more information. + Refer to for more information. diff --git a/en-US/D.xml b/en-US/D.xml index 8e8f0b3..100ef12 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -116,7 +116,7 @@ Needs review - When presenting specific dates and times numerically, see ISO Standard 8601. For dates, this means YYYMDD is the recommended representation. + When presenting specific dates and times numerically, refer to ISO Standard 8601. For dates, this means YYYMDD is the recommended representation. @@ -189,7 +189,7 @@ dialog box - See the Word Usage chapter of the IBM Style Guide for usage information related to this and similar terms. + Refer to the Word Usage chapter of the IBM Style Guide for usage information related to this and similar terms. @@ -231,7 +231,7 @@ disk, disc - Use "compact disc" or "hard disk". See the IBM Style Guide for more information and example use cases. + Use "compact disc" or "hard disk". Refer to the IBM Style Guide for more information and example use cases. @@ -273,7 +273,7 @@ documentation - When referring to the current manual set, use "documentation". For example, "This manual is also available as part of our online documentation." When referring to another manual, quote the title of the manual, for example, "See the Getting Started Guide for further information." + When referring to the current manual set, use "documentation". For example, "This manual is also available as part of our online documentation." When referring to another manual, quote the title of the manual, for example, "Refer to the Getting Started Guide for further information." @@ -316,7 +316,7 @@ downstream - Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "down-stream" or "down stream." + Correct. Use the one-word form for both the nominal and adjectival forms. Refer also to . Do not use "down-stream" or "down stream." diff --git a/en-US/Design.xml b/en-US/Design.xml index 8e6b7d7..7d3ccae 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -95,12 +95,12 @@ In training content, avoid using a verb such as "Discussing" or "Demonstrating" in objectives for students. Such verbs might refer instead to what the instructor or the course content covers, or to a student group activity in class. - See the IBM Style Guide for more information. + Refer to the IBM Style Guide for more information. Gerunds should be avoided elsewhere. - See . + Refer to . @@ -124,7 +124,7 @@
Documenting the User Interface - In all cases, see the IBM Style Guide for initial guidance. + In all cases, refer to the IBM Style Guide for initial guidance. The following sections highlight exceptions or cases that might otherwise cause confusion. @@ -166,7 +166,7 @@ - See the UI elements chapter in the IBM Style Guide for more information. + Refer to the UI elements chapter in the IBM Style Guide for more information.
Navigating Through Multiple UI Options @@ -249,11 +249,11 @@ "POSIX recommends these conventions for command line arguments. [...] Arguments are options if they begin with a hyphen delimiter ('-'). Multiple options may follow a hyphen delimiter in a single token if the options do not take arguments. Thus, '-abc' is equivalent to '-a -b -c'. [...] Certain options require an argument. For example, the '-o' option of the 'ld' command requires an argument—an output file name". and so on. - See info libc argument syntax for the full discussion. + Refer to info libc argument syntax for the full discussion. - See info bash and the IBM Style Guide for further guidance. + Refer to info bash and the IBM Style Guide for further guidance. The following examples are intended to highlight correct usage. @@ -585,7 +585,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest In the narrative, do not show the use of su or sudo, but always show privileged commands with the correct prompt. - See for information about command prompts. + Refer to for information about command prompts. @@ -637,7 +637,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest You can also use here documents to describe how to create a file with required content. - For more information about here documents, see + For more information about here documents, refer to The syntax of here documents varies by system, shell, language, and so on. The following example creates the my-script file in the current directory, with the example content. @@ -974,7 +974,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest Capitalization 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"); see the IBM Style Guide or another suitable reference if you are unsure. + Not all acronyms are capitalized (for example, "spool"); refer to the IBM Style Guide or another suitable reference if you are unsure. @@ -996,7 +996,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest Possessives - Do not use possessives with abbreviations. For examples and more information, see . + Do not use possessives with abbreviations. For examples and more information, refer to . @@ -1067,7 +1067,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest --> Do not use possessives to refer to product names. - For examples and more information, see . + For examples and more information, refer to . @@ -1266,7 +1266,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest When making a recommendation, the preferred verbiage is "Red Hat recommends ..." instead of the common but indirect "It is recommended ...". Recommendations can include best practices, recommended practices, and product-specific suggestions. - See for information on using the terms "best practices" and "recommended practices" in Red Hat documentation. + Refer to for information on using the terms "best practices" and "recommended practices" in Red Hat documentation. @@ -1341,7 +1341,7 @@ Book Title by First name Surname; Publisher. </listitem> <listitem> <para> - If the URL is excessively long or complex, create a link by using the title of the destination as a label, and put the actual URL in a footnote. For example: See the <ulink url="http://world-database-of-everything.com/en/classifcation_of_species/mammals.html"><citetitle>Classification of Species</citetitle></ulink><footnote> <para> + If the URL is excessively long or complex, create a link by using the title of the destination as a label, and put the actual URL in a footnote. For example: Refer to the <ulink url="http://world-database-of-everything.com/en/classifcation_of_species/mammals.html"><citetitle>Classification of Species</citetitle></ulink><footnote> <para> http://world-database-of-everything.com/en/classifcation_of_species/mammals.html </para> </footnote> page for more information. diff --git a/en-US/E.xml b/en-US/E.xml index 6620c31..700ca00 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -30,7 +30,7 @@ <listitem> <para> Use to refer to earlier releases of products. Do not use "older" or related terms. - See also <xref linkend="later" />. + Refer also to <xref linkend="later" />. </para> </listitem> @@ -50,7 +50,7 @@ <term>emdash</term> <listitem> <para> - Used (informally) to indicate a pause or abrupt change in thought; for emphasis; or to set off a series in a phrase. See <xref linkend="dash" /> for more information. + Used (informally) to indicate a pause or abrupt change in thought; for emphasis; or to set off a series in a phrase. Refer to <xref linkend="dash" /> for more information. </para> </listitem> @@ -67,7 +67,7 @@ When referring to typing a command, use "type" instead, such as "To open Source-Navigator from the command line, type <systemitem>snavigator</systemitem>." </para> <para> - When typing information into a single-field dialog box, "enter" means "type and press <keycap>Enter</keycap>". An example is "enter the license number". For multi-field dialog boxes, see "type". + When typing information into a single-field dialog box, "enter" means "type and press <keycap>Enter</keycap>". An example is "enter the license number". For multi-field dialog boxes, refer to "type". </para> </listitem> diff --git a/en-US/F.xml b/en-US/F.xml index 81324ec..7fa8f28 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -94,7 +94,7 @@ <term>file extensions (general usage)</term> <listitem> <para> - See <citetitle>File names, file types, and directory names</citetitle> in the <citetitle>IBM Style Guide</citetitle>. + Refer to <citetitle>File names, file types, and directory names</citetitle> in the <citetitle>IBM Style Guide</citetitle>. </para> </listitem> @@ -104,7 +104,7 @@ <term>file mode, file name, file system, file type</term> <listitem> <para> - <emphasis>n.</emphasis> Write as shown, two words, unless used as a variable. See the <citetitle>IBM Style Guide</citetitle> for more information. + <emphasis>n.</emphasis> Write as shown, two words, unless used as a variable. Refer to the <citetitle>IBM Style Guide</citetitle> for more information. </para> <para> <emphasis>adj.</emphasis> Hyphenate when used as a compound adjective. For example, "file-system attributes". @@ -117,7 +117,7 @@ <term>FireWire</term> <listitem> <para> - Correct. Do not use "Firewire" or "firewire". Although FireWire is a trademark of Apple Computer, it is not needed to append a trademark symbol, except to refer to Apple's FireWire software license or specific logos. See <ulink url="https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html">https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html</ulink>. + Correct. Do not use "Firewire" or "firewire". Although FireWire is a trademark of Apple Computer, it is not needed to append a trademark symbol, except to refer to Apple's FireWire software license or specific logos. Refer to <ulink url="https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html">https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html</ulink>. </para> <!-- Updated Apple trademark guidelines URL. --> @@ -243,7 +243,7 @@ <term>forwards compatible</term> <listitem> <para> - Do not use. Instead, use "compatible with later versions". See also <xref linkend="backwards-compatible" />. + Do not use. Instead, use "compatible with later versions". Refer also to <xref linkend="backwards-compatible" />. </para> </listitem> @@ -278,7 +278,7 @@ 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" />. + Refer also to <xref linkend="bimodal-it" />. </para> </listitem> @@ -297,7 +297,7 @@ Do not use "frontend" as a noun or adjective. </para> <para> - See also <xref linkend="back-end" />. + Refer also to <xref linkend="back-end" />. </para> </listitem> @@ -328,7 +328,7 @@ <term>fuzzy</term> <listitem> <para> - Correct only when referring to fuzzy searches. See <xref linkend="appropriate-language" /> for details and examples. + Correct only when referring to fuzzy searches. Refer to <xref linkend="appropriate-language" /> for details and examples. </para> <!-- Removed term capitalization for "fuzzy". --> diff --git a/en-US/G.xml b/en-US/G.xml index fb223ab..32e360a 100644 --- a/en-US/G.xml +++ b/en-US/G.xml @@ -146,7 +146,7 @@ <term>GigE</term> <listitem> <para> - See <xref linkend="gbe" />. + Refer to <xref linkend="gbe" />. </para> </listitem> @@ -166,7 +166,7 @@ <term>GNOME</term> <listitem> <para> - Correct. Do not use "gnome", "Gnome", or other variants. See also <xref linkend="gnome-classic" />. + Correct. Do not use "gnome", "Gnome", or other variants. Refer also to <xref linkend="gnome-classic" />. </para> </listitem> diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 50fa863..fe7ebfd 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -152,7 +152,7 @@ A <emphasis>possessive</emphasis> indicates that something or someone belongs to a person or thing. </para> <para> - For guidance on how to form a possessive, see <xref linkend="apostrophes"/>. + For guidance on how to form a possessive, refer to <xref linkend="apostrophes"/>. </para> <para> Do not use possessives with product names. @@ -950,7 +950,7 @@ Split contractions and abbreviations into separate paragraphs. --> 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>. + Refer also to the "Hyphens" topic in the <citetitle>IBM Style Guide</citetitle>. </para> <formalpara id="hyphenate-for-clarity"> diff --git a/en-US/H.xml b/en-US/H.xml index 5f87a4c..4758366 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -154,7 +154,7 @@ <term>host group</term> <listitem> <para> - <emphasis>n.</emphasis> Two words. Capitalize the "H" at the beginning of a sentence. See RFC 966 for more details. + <emphasis>n.</emphasis> Two words. Capitalize the "H" at the beginning of a sentence. Refer to RFC 966 for more details. </para> </listitem> @@ -166,7 +166,7 @@ <para> <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. + Refer to the <citetitle>IBM Style Guide</citetitle> for more information. </para> </listitem> @@ -217,7 +217,7 @@ <term>hover help</term> <listitem> <para> - See <xref linkend="tooltip" />. + Refer to <xref linkend="tooltip" />. </para> </listitem> @@ -237,7 +237,7 @@ <term>HTML</term> <listitem> <para> - When referring to the language, use "HTML", such as "To see the HTML version of this documentation ...". When referring to a web page extension, use "html", such as "The main page is <filename>index.html</filename>." + When referring to the language, use "HTML", such as "To refer to the HTML version of this documentation ...". When referring to a web page extension, use "html", such as "The main page is <filename>index.html</filename>." </para> </listitem> @@ -260,7 +260,7 @@ <term>hybrid IT</term> <listitem> <para> - The preferred term to refer to IT that spans both traditional and modern infrastructure, or private and public environments, or some combination of them. Because hybrid can indicate either infrastructure or environment, or both, be specific about the underlying combination. See also <xref linkend="bimodal-it" />. + The preferred term to refer to IT that spans both traditional and modern infrastructure, or private and public environments, or some combination of them. Because hybrid can indicate either infrastructure or environment, or both, be specific about the underlying combination. Refer also to <xref linkend="bimodal-it" />. </para> </listitem> diff --git a/en-US/I.xml b/en-US/I.xml index 541daeb..8765b10 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -20,7 +20,7 @@ <term>IaaS</term> <listitem> <para> - Correct. This is the correct abbreviation for "Infrastructure-as-a-Service". See also <xref linkend="paas" />. + Correct. This is the correct abbreviation for "Infrastructure-as-a-Service". Refer also to <xref linkend="paas" />. </para> </listitem> @@ -142,16 +142,16 @@ When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. </para> <para> - See also <xref linkend="AMD64"/>. + Refer also to <xref linkend="AMD64"/>. </para> <note> <para> The AMD64 logo is trademarked; the term "AMD64" is not. - For more information about AMD trademarks, see the <citetitle>AMD Trademark Information</citetitle> page at <ulink url="https://www.amd.com/en/corporate/trademarks" />. + For more information about AMD trademarks, refer to the <citetitle>AMD Trademark Information</citetitle> page at <ulink url="https://www.amd.com/en/corporate/trademarks" />. </para> <!-- Updated URL for AMD trademarks. --> <para> - For more information about Intel® trademarks, see <ulink url="http://www.intel.com/content/www/us/en/legal/trademarks.html" /> and <ulink url="http://www.intel.com/content/www/us/en/trademarks/trademarks.html" />. + For more information about Intel® trademarks, refer to <ulink url="http://www.intel.com/content/www/us/en/legal/trademarks.html" /> and <ulink url="http://www.intel.com/content/www/us/en/trademarks/trademarks.html" />. </para> </note> @@ -252,7 +252,7 @@ <term>Intranet, intranet</term> <listitem> <para> - See the "Word usage" appendix of the <citetitle>IBM Style Guide</citetitle> for guidance. + Refer to the "Word usage" appendix of the <citetitle>IBM Style Guide</citetitle> for guidance. </para> </listitem> diff --git a/en-US/K.xml b/en-US/K.xml index 31efa55..6ab0f29 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -10,7 +10,7 @@ <term>KB, kB</term> <listitem> <para> - See the <citetitle>IBM Style Guide</citetitle> for the correct abbreviation to use for specific use cases. + Refer to the <citetitle>IBM Style Guide</citetitle> for the correct abbreviation to use for specific use cases. </para> </listitem> @@ -93,7 +93,7 @@ When referring to a keyboard key, it is uppercase, singular, and the word "key" is not necessary, such as "To exit, press X". When the <keycap>Ctrl</keycap> or <keycap>Alt</keycap> keys are needed, use a plus sign between the keys, such as "To save the file, press "Ctrl+S". </para> <para> - See also <xref linkend="spacebar" />. + Refer also to <xref linkend="spacebar" />. </para> </listitem> @@ -119,7 +119,7 @@ <term>keytab</term> <listitem> <para> - <emphasis>n.</emphasis> <emphasis>(Kerberos)</emphasis> Correct. A keytab (short for "key table") stores long-term keys for one or more principals. For details, see <ulink url="https://web.mit.edu/kerberos/krb5-1.12/doc/basic/keytab_def.html" />. + <emphasis>n.</emphasis> <emphasis>(Kerberos)</emphasis> Correct. A keytab (short for "key table") stores long-term keys for one or more principals. For details, refer to <ulink url="https://web.mit.edu/kerberos/krb5-1.12/doc/basic/keytab_def.html" />. </para> </listitem> diff --git a/en-US/L.xml b/en-US/L.xml index b37b011..28eeb77 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -42,7 +42,7 @@ <term>later</term> <listitem> <para> - Use to refer to later or more recent releases of products. Do not use "newer" or related terms. See also <xref linkend="earlier" />. + Use to refer to later or more recent releases of products. Do not use "newer" or related terms. Refer also to <xref linkend="earlier" />. </para> </listitem> @@ -77,7 +77,7 @@ A Linux desktop suite. Do not use "Libre", "Libreoffice", or "Libre Office". </para> <para> - See also <xref linkend="openoffice" /> + Refer also to <xref linkend="openoffice" /> </para> </listitem> @@ -226,17 +226,14 @@ </varlistentry> <varlistentry id="lookup"> - <term>lookup, look-up, look up</term> + <term>lookup, look up</term> <listitem> <para> - <emphasis>n.</emphasis> Use the one-word form. + <emphasis>n., adj.</emphasis> Use the one-word form, unhyphenated. </para> <para> <emphasis>v.</emphasis> Use the two-word form. </para> - <para> - <emphasis>adj.</emphasis> Hyphenate when used as a modifier. For example, "a look-up table". - </para> </listitem> diff --git a/en-US/Language.xml b/en-US/Language.xml index 967133d..9c05b08 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -33,7 +33,7 @@ This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices". </para> <para> - See the section <xref linkend="making-recommendations" /> for additional information about recommendations in Red Hat documentation. + Refer to the section <xref linkend="making-recommendations" /> for additional information about recommendations in Red Hat documentation. </para> </listitem> @@ -240,7 +240,7 @@ <para> "Visit the following web link to dig deeper into [subject] ...". Using "dig deeper" might translate awkwardly. - Consider rewording: "For detailed information regarding [subject], see [link]." + Consider rewording: "For detailed information regarding [subject], refer to [link]." </para> </listitem> @@ -820,7 +820,7 @@ <term>virtual elephants</term> <listitem> <para> - This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture". Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet", "dark horse", "black sheep", and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. See <ulink url="http://en.wikipedia.org/wiki/Blind_Men-anElephant">http://en.wikipedia.org/wiki/Blind_Men-anElephant</ulink> for more information. + This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture". Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet", "dark horse", "black sheep", and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. Refer to <ulink url="http://en.wikipedia.org/wiki/Blind_Men-anElephant">http://en.wikipedia.org/wiki/Blind_Men-anElephant</ulink> for more information. </para> </listitem> @@ -1262,7 +1262,7 @@ </table> <note> <para> - See also <xref linkend="genders" />. + Refer also to <xref linkend="genders" />. </para> </note> @@ -1634,7 +1634,7 @@ Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate groups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). </para> <para> - See <citetitle>The Chicago Manual of Style, 17th Edition</citetitle> for detailed information on numbering formats. + Refer to <citetitle>The Chicago Manual of Style, 17th Edition</citetitle> for detailed information on numbering formats. </para> <!-- Moved Telephone numbers entry here from T section, and renamed to Phone numbers. --> diff --git a/en-US/M.xml b/en-US/M.xml index e35a362..d16639b 100644 --- a/en-US/M.xml +++ b/en-US/M.xml @@ -194,7 +194,7 @@ <term>microservice </term> <listitem> <para> - <emphasis>n.</emphasis> Correct. One word, common noun. Do not use "micro-service" or "micro service". Only capitalize at the beginning of a sentence or in a title. See <ulink url="https://en.wikipedia.org/wiki/Microservices">https://en.wikipedia.org/wiki/Microservices</ulink> for a definition. + <emphasis>n.</emphasis> Correct. One word, common noun. Do not use "micro-service" or "micro service". Only capitalize at the beginning of a sentence or in a title. Refer to <ulink url="https://en.wikipedia.org/wiki/Microservices">https://en.wikipedia.org/wiki/Microservices</ulink> for a definition. </para> </listitem> diff --git a/en-US/N.xml b/en-US/N.xml index 4feaff4..d2fb950 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -117,7 +117,7 @@ <listitem> <para> Generally, use "number sign" to refer to the # character. - Otherwise, 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. + Otherwise, use "hash" to refer to a hashtag in social media, or to refer to Secure Hash Algorithm (refer to <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. </para> diff --git a/en-US/New.xml b/en-US/New.xml index 4f665e9..5b08a1b 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -13,66 +13,66 @@ <itemizedlist> <listitem> <para>Updated audience information for this guide. - See <xref linkend="audience"/>.</para> + Refer to <xref linkend="audience"/>.</para> </listitem> <listitem> <para>Updated guidance about writing titles. - See <xref linkend="verbs-titles"/>.</para> + Refer to <xref linkend="verbs-titles"/>.</para> </listitem> <listitem> <para>Updated guidance on continuation prompts. - See <xref linkend="continuation"/>.</para> + Refer to <xref linkend="continuation"/>.</para> </listitem> <listitem> <para>Updated using realistic usernames. - See <xref linkend="using-realistic-names"/>.</para> + Refer to <xref linkend="using-realistic-names"/>.</para> </listitem> <listitem> <para>Added guidance on omitting part of an output. - See <xref linkend="omitting"/>.</para> + Refer to <xref linkend="omitting"/>.</para> </listitem> <listitem> <para>Added guidance about possessives with product names and abbreviations. - See <xref linkend="possessives"/>.</para> + Refer to <xref linkend="possessives"/>.</para> </listitem> <listitem> <para>Various additions to the Punctuation section. - See <xref linkend="punctuation"/>.</para> + Refer to <xref linkend="punctuation"/>.</para> </listitem> <listitem> <para>Restructured "Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly". - See <xref linkend="abbreviations-correctly"/>.</para> + Refer to <xref linkend="abbreviations-correctly"/>.</para> </listitem> <listitem> <para>Rewrote "The Repeatability Test" section and renamed it to "Repetition". - See <xref linkend="repeatability-test"/>.</para> + Refer to <xref linkend="repeatability-test"/>.</para> </listitem> <listitem> <para>Changed "Homographic Verbs" subsection title to "Avoid May and Should". - See <xref linkend="homographs"/>.</para> + Refer to <xref linkend="homographs"/>.</para> </listitem> <listitem> <para>Inclusive naming of default branch. - See <xref linkend="inclusive-language"/>.</para> + Refer to <xref linkend="inclusive-language"/>.</para> </listitem> <listitem> <para>Updated IBM Style access information. - See <xref linkend="tech-content-refs"/>.</para> + Refer to <xref linkend="tech-content-refs"/>.</para> </listitem> <listitem> <para>Adjusted sentence length guideline. - See <xref linkend="length"/>.</para> + Refer to <xref linkend="length"/>.</para> </listitem> <listitem> <para>Removed some references that were specific to DocBook.</para> </listitem> <listitem> <para>Use "team" or "group" instead of "squad". - See <xref linkend="squad"/>.</para> + Refer to <xref linkend="squad"/>.</para> </listitem> <listitem> <para>New or updated usage entries: application velocity, key ring, Metal-as-a-Service, OTP, smart card, systemwide, virtualized. - See <xref linkend="part-Usage_Dictionary"/>.</para> + Refer to <xref linkend="part-Usage_Dictionary"/>.</para> </listitem> <listitem> <para>Various other fixes.</para> diff --git a/en-US/O.xml b/en-US/O.xml index 1278f07..69ce00e 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -139,7 +139,7 @@ <listitem> <para> Do not use. - See <xref linkend="onpremise"/>. + Refer to <xref linkend="onpremise"/>. </para> </listitem> @@ -177,7 +177,7 @@ 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". + Refer also to "kernel panic". </para> </listitem> @@ -207,7 +207,7 @@ <term>Open InfiniBand</term> <listitem> <para> - "Open InfiniBand" is deprecated and should not be used. See "InfiniBand" for usage rules regarding the current preferred term for this switched fabric network topology. + "Open InfiniBand" is deprecated and should not be used. Refer to "InfiniBand" for usage rules regarding the current preferred term for this switched fabric network topology. </para> </listitem> @@ -228,7 +228,7 @@ A Linux desktop suite. Do not use "Openoffice", "Open Office", or "ooo". </para> <para> - See also <xref linkend="libreoffice" />. + Refer also to <xref linkend="libreoffice" />. </para> </listitem> @@ -307,7 +307,7 @@ <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" />. + Refer also to <xref linkend="undercloud" />. </para> </listitem> diff --git a/en-US/P.xml b/en-US/P.xml index 92f8b79..5a0c92b 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -20,7 +20,7 @@ </warning> <para> - See also <xref linkend="saas" />. + Refer also to <xref linkend="saas" />. </para> </listitem> @@ -52,7 +52,7 @@ <emphasis>n.</emphasis> Use PHP when referring to the language in general. Use <command>php</command> when referring to the specific command or some other literal use. </para> <para> - See <ulink url="http://www.php.net/" /> for specific PHP language information. See <ulink url="http://en.wikipedia.org/wiki/PHP" /> for more general information. + Refer to <ulink url="http://www.php.net/" /> for specific PHP language information. Refer to <ulink url="http://en.wikipedia.org/wiki/PHP" /> for more general information. </para> </listitem> @@ -89,7 +89,7 @@ <listitem> <para> Do not use. - Instead of saying "Please see the <citetitle>Getting Started Guide</citetitle>", use "See the <citetitle>Getting Started Guide."</citetitle> + Instead of saying "Please refer to the <citetitle>Getting Started Guide</citetitle>", use "Refer to the <citetitle>Getting Started Guide."</citetitle> </para> <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. @@ -129,7 +129,7 @@ For times of day, use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "2 PM". </para> <para> - See also <xref linkend="am"/>. + Refer also to <xref linkend="am"/>. </para> </listitem> diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 2b29564..156241f 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -563,7 +563,7 @@ PLAY [Gather and display facts for managed nodes] ****************************</ Using project "default". </screen> <para> - As you can see in the previous image, the title of the web page is "OpenShift 3 Etherpad". + As in the previous image, the title of the web page is "OpenShift 3 Etherpad". </para> <para> In the program segment, ensure that the value is X'FF'. @@ -611,7 +611,7 @@ PLAY [Gather and display facts for managed nodes] ****************************</ Singular proper names ending in <emphasis>s</emphasis> only need an apostrophe (for example, Dickens' novels). </para> <para> - For guidance on whether to use a possessive, see <xref linkend="possessives"/>. + For guidance on whether to use a possessive, refer to <xref linkend="possessives"/>. </para> @@ -783,7 +783,7 @@ PLAY [Gather and display facts for managed nodes] ****************************</ </para> </example> <para> - For more details, see the <citetitle>IBM Style Guide</citetitle>. + For more details, refer to the <citetitle>IBM Style Guide</citetitle>. </para> </section> diff --git a/en-US/R.xml b/en-US/R.xml index 1d43bc7..7c7adf5 100644 --- a/en-US/R.xml +++ b/en-US/R.xml @@ -118,7 +118,8 @@ <term>refer to</term> <listitem> <para> - Do not use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source). Use "See". + Use to provide references within a document, and for cross-references to other resources. + <!-- Do not use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source). Use "See". --> </para> </listitem> @@ -149,7 +150,7 @@ <term>required</term> <listitem> <para> - See <xref linkend="must" />. + Refer to <xref linkend="must" />. </para> </listitem> @@ -159,7 +160,7 @@ <term>return</term> <listitem> <para> - When referring to the keyboard key on Solaris or Mac, use <keycap>Return</keycap> or <keycap>return</keycap>, respectively. See <xref linkend="enter" /> for other platforms. + When referring to the keyboard key on Solaris or Mac, use <keycap>Return</keycap> or <keycap>return</keycap>, respectively. Refer to <xref linkend="enter" /> for other platforms. </para> </listitem> diff --git a/en-US/S.xml b/en-US/S.xml index 12575ae..2304099 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -21,7 +21,7 @@ <listitem> <para> The correct abbreviation for "Software-as-a-Service". - See also <xref linkend="paas" />. + Refer also to <xref linkend="paas" />. </para> </listitem> @@ -47,11 +47,11 @@ </listitem> </varlistentry> - <varlistentry id="screen-capture"> - <term>screen capture</term> + <varlistentry id="screenshot"> + <term>screenshot</term> <listitem> <para> - <emphasis>n.</emphasis> Do not use "screen shot", "screenshot", or other terms or variations. See the relevant entry in the <citetitle>IBM Style Guide.</citetitle> + <emphasis>n.</emphasis> Use this term, and write as one word. Do not use other terms or variations. </para> </listitem> @@ -82,7 +82,7 @@ <listitem> <para> <emphasis>n., vb.</emphasis> Due to potential legal ramifications, do not use without a qualifier. - See <xref linkend="qualify-sensitive-terms"/> for examples. + Refer to <xref linkend="qualify-sensitive-terms"/> for examples. </para> <table id="qualify-sensitive-terms"><title>Using Qualifiers with Sensitive Terms @@ -112,13 +112,18 @@ - + see - Use to refer readers to another resource. Avoid using "refer to" in this context. + For references within a document, and for cross-references to other resources, do not use “see”. Use “refer to”. + + + For descriptions of graphics, explanations of command outputs, and other similar cases, it is acceptable to use “see”. + Alternatively, it might be more concise or precise to replace “see” with another verb in these cases. + For example, instead of using "Click a server link to see the result details", you could use "Click a server link for the result details". + Instead of using "As you can see, these expected Audit events have an AVC Audit record", you could use "As shown in the output, these expected Audit events have an AVC Audit record". - @@ -129,7 +134,7 @@ n. Only use the abbreviation "segfault" if absolutely necessary, and never use it as a verb. - See also "What is a segfault?" on the Red Hat Customer Portal for more information. + Refer also to "What is a segfault?" on the Red Hat Customer Portal for more information. @@ -171,7 +176,7 @@ server-side/server side - See . + Refer to . @@ -221,7 +226,7 @@ Thus "SHA224", "SHA256", "SHA384", and "SHA512" are considered correct when referring to these specific hash functions. - See for full details. + Refer to for full details. @@ -306,7 +311,7 @@ Do not use if it is something the user must do. For example, "You should make a backup" is a suggestion, but "You must make a backup" is a requirement. - See also . + Refer also to . @@ -345,7 +350,7 @@ simply - Do not use. See also . + Do not use. Refer also to . @@ -367,7 +372,7 @@ skill set, skills, knowledge - n. Avoid using "skill set" as much as possible; use "skills" or "knowledge" instead. Do not use "skill set" or "skill-set" as an adjective. Do not use "skill-set knowledge"; it is redundant. See the following examples: + n. Avoid using "skill set" as much as possible; use "skills" or "knowledge" instead. Do not use "skill set" or "skill-set" as an adjective. Do not use "skill-set knowledge"; it is redundant. Refer to the following examples: Example Use of Term "Skillset" Versus "Skills" @@ -684,7 +689,7 @@ a programming and technical sense, it also means "Run the source--help is an option. - See also . + Refer also to . @@ -694,7 +699,7 @@ a programming and technical sense, it also means "Run the sourcesubdirectory - Correct. Do not use "sub-directory". See also . + Correct. Do not use "sub-directory". Refer also to . @@ -704,7 +709,7 @@ a programming and technical sense, it also means "Run the sourcesubmenu - Correct. Do not use "sub-menu". See also . + Correct. Do not use "sub-menu". Refer also to . @@ -756,7 +761,7 @@ a programming and technical sense, it also means "Run the sourceSAP Sybase Adaptive Server Enterprise (ASE) in the first instance. Subsequent entries can use the abbreviation "Sybase ASE". If discussing the high-availability version, use "Sybase ASE and High Availability". - See http://www.sybase.com/products/databasemanagement/adaptiveserverenterprise for more information. + Refer to http://www.sybase.com/products/databasemanagement/adaptiveserverenterprise for more information. diff --git a/en-US/T.xml b/en-US/T.xml index 14c8b70..953ba0f 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -20,7 +20,7 @@ tar, tarball - n. See the Word Usage chapter of the IBM Style Guide. + n. Refer to the Word Usage chapter of the IBM Style Guide. @@ -30,11 +30,11 @@ telco - Preferred abbreviation for "telecommunications company". Do not use "telecom". See also . + Preferred abbreviation for "telecommunications company". Do not use "telecom". Refer also to . Use "telecommunications service provider" on first use. Subsequent uses can be "telco" or "telco service provider"; only use "telco" when the context makes it clear that the industry is engaged in providing telecommunications services. Use in URLs. - See . + Refer to . @@ -44,7 +44,7 @@ telecommunications service provider - Expand fully on first use, after which "telco" is the preferred abbreviation. "Service provider" is also acceptable as an abbreviation, but be careful in content that mentions different industries or types of services. Do not use in URLs. See . + Expand fully on first use, after which "telco" is the preferred abbreviation. "Service provider" is also acceptable as an abbreviation, but be careful in content that mentions different industries or types of services. Do not use in URLs. Refer to . @@ -70,7 +70,7 @@ n. Do not use to describe where to type commands. Use "command line" instead. - See the Word Usage chapter of the IBM Style Guide for more information. + Refer to the Word Usage chapter of the IBM Style Guide for more information. @@ -133,7 +133,7 @@ throughput - n. The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. See the IBM Style Guide for more information about using measurements and abbreviations. + n. The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. Refer to the IBM Style Guide for more information about using measurements and abbreviations. @@ -174,7 +174,7 @@ n. When capitalized, Token-Ring refers to the PC network architecture that IBM developed. The IBM Token-Ring specification is standardized by the IEEE as the IEEE 802.5 standard. - + @@ -204,7 +204,7 @@ totally - Do not use. See "basically". + Do not use. Refer to "basically". diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 9d0220e..726b582 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -111,7 +111,7 @@ - The following discussion provides some initial insight into using lists correctly. See the IBM Style Guide for a full discussion. + The following discussion provides some initial insight into using lists correctly. Refer to the IBM Style Guide for a full discussion. Do not insert a list midway through a sentence and then continue the sentence after the list. @@ -468,7 +468,7 @@ - For information about punctuation in lead-in sentences that introduce a list, see . + For information about punctuation in lead-in sentences that introduce a list, refer to .
@@ -661,7 +661,7 @@ rhevm-iso-uploader [options] upload [file1] [file2] [file3] - For information about punctuation in lead-in sentences that introduce a code block, see . + For information about punctuation in lead-in sentences that introduce a code block, refer to .
@@ -708,7 +708,7 @@ - Do not include entities such as &PRODNAME; or &VERSION; and so on, or things like &BIBLE; to represent "The King James Bible". To learn more about entities, see the relevant chapter in + Do not include entities such as &PRODNAME; or &VERSION; and so on, or things like &BIBLE; to represent "The King James Bible". To learn more about entities, refer to the relevant chapter in
diff --git a/en-US/U.xml b/en-US/U.xml index 5794a9f..5ce86bf 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -38,7 +38,7 @@ n. Always lowercase. It is a concept, not a technology or product name. Being a common noun, it normally requires an article. - See also . + Refer also to . @@ -143,7 +143,7 @@ upstream - Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "up-stream" or "up stream". + Correct. Use the one-word form for both the nominal and adjectival forms. Refer also to . Do not use "up-stream" or "up stream". @@ -166,7 +166,7 @@ n. Include the appropriate protocol, such as http, ftp, or https, at the beginning of URLs. That is, use http://www.redhat.com and not www.redhat.com. - See for more information. + Refer to for more information. @@ -209,7 +209,7 @@ n. Usually one word. Capitalize the "U" at the beginning of a sentence. - See the IBM Style Guide for more information. + Refer to the IBM Style Guide for more information. diff --git a/en-US/V.xml b/en-US/V.xml index 5cefe1a..31f895c 100644 --- a/en-US/V.xml +++ b/en-US/V.xml @@ -111,7 +111,7 @@ The term "virtualized guest" should be used only when comparing a "fully virtualized guest" with a "paravirtualized guest". - See also "guest operating system". + Refer also to "guest operating system". diff --git a/en-US/WUG_Intro.xml b/en-US/WUG_Intro.xml index 834f63b..48ec227 100644 --- a/en-US/WUG_Intro.xml +++ b/en-US/WUG_Intro.xml @@ -17,7 +17,7 @@ The status of a trademark can vary from country to country. Therefore, do not attach the symbols for trademark or registered trademark (™ and ®) to any third-party trademarks that you mention in your document unless Red Hat legal asks you to do so. We do mark Red Hat trademarks. - See Copyright Notices and Trademark Legends for more information. + Refer to Copyright Notices and Trademark Legends for more information. diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index c7082ee..5ffef67 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -102,7 +102,7 @@ zip - See the Word Usage chapter of the IBM Style Guide. + Refer to the Word Usage chapter of the IBM Style Guide. From 0c182dff06c47c574425894753e4b85584d0a109 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Mon, 27 Nov 2023 17:19:58 +0000 Subject: [PATCH 32/79] Line continuation for multiple operating systems (#548) * Line continuation for multiple operating systems * Minor edit --- en-US/Design.xml | 54 ++++++++++++++++++++++-------------------------- 1 file changed, 25 insertions(+), 29 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 7d3ccae..b772694 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -425,6 +425,21 @@ $ vi myFile.txt Use line continuation characters without the associated PS2 prompts. + + + + On Linux and macOS operating systems, use the Linux shell continuation character (\). + + + + + On Windows operating systems, use the backtick character (`). + + + + + For content that is potentially used in multiple operating systems, use the Linux shell continuation character, and include an explanatory sentence before the command. + - - -Wrapping Long Commands with Continuation Characters and Without PS2 Prompts +$ aws iam create-policy --policy-name RosaCloudWatch \ + --policy-document file://policy.json --query Policy.Arn --output text +arn:aws:iam::452954386616:policy/RosaCloudWatch + - This example uses continuation characters but not PS2 prompts. - -[root@node]# cephadm bootstrap --mon-ip=MON_IP --registry-url=registry.redhat.io \ ---registry-username=REGISTRY_USERNAME --registry-password=REGISTRY_PASSWORD \ ---initial-dashboard-password=DASHBOARD_PASSWORD --dashboard-password-noupdate \ ---allow-fqdn-hostname - +The ARN in the preceding output is different on your system. +
From 1fb8f6c0cd3b164dd4dae2d3a64ab8eda62a1445 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Tue, 28 Nov 2023 17:11:35 +0000 Subject: [PATCH 33/79] Add 64-bit architecture guidance (#547) * Add 64-bit architecture guidance * Implementing edits from review --- en-US/0-9.xml | 71 ++++++++++++++++++++++++++++++ en-US/A.xml | 116 +++++++++++++++++++++++++++++++++++++++++++++++--- en-US/I.xml | 31 +++++++++++--- en-US/XYZ.xml | 35 +++++++++++++++ 4 files changed, 239 insertions(+), 14 deletions(-) diff --git a/en-US/0-9.xml b/en-US/0-9.xml index 76d5120..e2d62cb 100644 --- a/en-US/0-9.xml +++ b/en-US/0-9.xml @@ -38,6 +38,77 @@ + + 64-bit ARM + + + n. A 64-bit version of the ARM architecture. + This term can refer to both AArch66/`aarch64` and to ARM64/`arm64`. + + + Use this format in general cases to refer to names of the architecture for various cloud providers. + + + 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. + + + Examples: + + + + + Amazon Web Services (AWS) on 64-bit ARM systems + + + + + Machine types for Microsoft Azure on 64-bit ARM infrastructures + + + + + Refer also to , , , , , and . + + + + + + + 64-bit x86 + + + n. A 64-bit version of the x86 architecture. + This term is a synonym of x86_64. + Use this format in general cases to refer to names of the architecture for various cloud providers. + + + 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. + + + Examples: + + + + + Amazon Web Services (AWS) on 64-bit x86 systems + + + + + Machine types for Microsoft Azure on 64-bit x86 infrastructures + + + + + Refer also to , , , , , and . + + + + + + diff --git a/en-US/A.xml b/en-US/A.xml index af66767..72791ed 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -102,21 +102,84 @@ + + + AArch64, aarch64 + + + n. A 64-bit version of the ARM architecture. + Use this term when referring to operating systems and server instances, for example Red Hat Enterprise Linux, Fedora, CoreOS, and other Linux distributions. + + + 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. + It can be styled as code (monospace font or a code-styled block) when referring to code. + + + 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. + + + Examples: + + + + + When running Red Hat Enterprise Linux with an AArch64 system, run the following commands: + + + + + Specify the system architecture of your cluster, such as x86_64 or aarch64. + + + + + Refer also to , , , , , and . + + + + - AMD64 + AMD64, amd64 - Correct. Do not use "Hammer", "x86_64", "x86-64", "x64", "64-bit x86" or other variations as the name of this architecture. + n. The AMD 64-bit version of the x86 architecture. + Use this term for Red Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), or command-line interface (CLI) objects. - The correct term for AMD's implementation of this architecture is "AMD64". - When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. + Use the uppercase format (AMD64) in general sentences when referring to Red Hat OpenShift Container Platform features. + 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. + + + 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. + + + Examples: + + + + This operator is supported on AMD64 and ARM64 platforms. + + + + + In this scenario, amd64 is a valid value for X. + + + + - Refer also to . + Refer also to , , , , , and . - + + + + + + + ARM64, arm64 + + + n. A 64-bit version of the ARM architecture. + Use this term for Red Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), and command-line interface (CLI) objects. + + + Use the uppercase format (ARM64) in general sentences when referring to Red Hat OpenShift Container Platform features. + 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. + + + 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. + + + Examples: + + + + + In this exercise, you create an ARM64 compute machine set. + + + + + In this scenario, arm64 is a valid value for X. + + + + + Refer also to , , , , , and . + + and/or diff --git a/en-US/I.xml b/en-US/I.xml index 8765b10..9b603c5 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -134,24 +134,41 @@ Intel 64 - Correct. + n. The Intel 64-bit version of the x86 architecture. + Use this format when referring to information that is exclusive to Intel processors. + For Red Hat products, use only for Red Hat Enterprise Linux content. + + + 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. + + + Example: + + + + + This feature can run on only Intel 64 processors. + + + + - Refer also to . + Refer also to , , , , , and . - + + --> - For more information about Intel® trademarks, refer to and . + For more information about Intel trademarks, refer to and . diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index 5ffef67..1d0bf21 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -16,6 +16,41 @@ + + x86_64 + + + n. A 64-bit version of the x86 architecture. + Use this term when referring to operating systems and server instances, for example Red Hat Enterprise Linux, Fedora, CoreOS and other Linux distributions. + Use this format without backticks in general cases when referring to system architecture. + Use this format in backticks when referring to architecture as a value or parameter. + + + 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. + + + Examples: + + + + + Specifies the type of architecture for your server, such as x86_64. + + + + + When specifying the architecture, x86_64 is a valid value. + + + + + Refer also to , , , , , and . + + + + + XEmacs From e1f9e88a6cfa608b6cec60933f60c01fdb8631e2 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Thu, 21 Dec 2023 16:56:31 -0800 Subject: [PATCH 34/79] Updated Boolean guidance and a bug fix (#551) * Updated Boolean guidance and a bug fix * Update to Boolean entry --- en-US/B.xml | 13 +++++++++++-- en-US/Grammar.xml | 2 +- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/en-US/B.xml b/en-US/B.xml index af67e4c..b72d4c5 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -227,9 +227,18 @@ Correct. Named after George Boole, who first developed the concept. - According to the IBM Style Guide, it is acceptable to use "boolean" in API programming information when it refers to a primitive return type. + According to the IBM Style Guide, it is acceptable to use "boolean" (lowercase) in API programming information when it refers to a primitive return type. - + + To set Boolean values in YAML files, use true or false, written lowercase, rather than yes or no, because YAML 1.2 and later versions do not support the latter syntax. + + + For example, the following scenario specifies that a task is run only one time: + +- name: Pause 30 seconds + ansible.builtin.pause: + seconds: 30 + run_once: true diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index fe7ebfd..e882786 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -932,7 +932,7 @@ Split contractions and abbreviations into separate paragraphs. --> Contractions and Abbreviations Do not use contractions in Red Hat documents. - For example, do not use can't, "don't", "won't", and similar examples. + 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. From 1d86161db7e2cdb81e9dcd0be60489afa2b06701 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 3 Jan 2024 09:14:47 +0000 Subject: [PATCH 35/79] Reworked entries for tar, tarball, untar, unzip, zip (#552) --- en-US/T.xml | 31 +++++++++++++++++++++++++------ en-US/U.xml | 22 ++++++++++++++++++++++ en-US/XYZ.xml | 1 + 3 files changed, 48 insertions(+), 6 deletions(-) diff --git a/en-US/T.xml b/en-US/T.xml index 953ba0f..dd11d8f 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -6,21 +6,40 @@ T - - taskbar + + tar - n. One word. Do not use "task bar". + n., adj. The tape archive file format. + Only use in reference to the file format, for example "a .tar file". + Refer to the Word Usage chapter of the IBM Style Guide. + + + v. Do not use to refer to the process of creating a .tar file. + Refer to the Word Usage chapter of the IBM Style Guide. - - tar, tarball + + tarball - n. Refer to the Word Usage chapter of the IBM Style Guide. + n. In most cases, do not use "tarball" to refer to a compressed archive in the .tar format. + Use ".tar file". + In some limited cases, "tarball" might be introduced as a commonly used term for a compressed archive in the .tar format. + In such cases, briefly mentioning the term as an alternative name might be acceptable, but do not use "tarball" as the primary term to refer to compressed archives. + + + + + + + taskbar + + + n. One word. Do not use "task bar". diff --git a/en-US/U.xml b/en-US/U.xml index 5ce86bf..b63c408 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -88,6 +88,17 @@ + + + untar + + + v. Do not use. + Refer to the Word Usage chapter of the IBM Style Guide. + + + + untrusted @@ -98,6 +109,17 @@ + + + unzip + + + v. Do not use. + Refer to the Word Usage chapter of the IBM Style Guide. + + + + upgrade diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index 1d0bf21..48dd375 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -137,6 +137,7 @@ zip + v. Do not use. Refer to the Word Usage chapter of the IBM Style Guide. From 5ce7b811d1dcede9c331ce082597f3a109128414 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Thu, 18 Jan 2024 19:36:47 +0000 Subject: [PATCH 36/79] Clarify capitalization for table titles (#553) --- en-US/Cross_references.xml | 2 +- en-US/Design.xml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/en-US/Cross_references.xml b/en-US/Cross_references.xml index aba9f6b..623cb63 100644 --- a/en-US/Cross_references.xml +++ b/en-US/Cross_references.xml @@ -29,7 +29,7 @@ Does the paragraph or section consist largely of links? - In running text, each paragraph should contain no more than a couple of links. Links should not occur in every paragraph, and they must not occur in titles, subheadings, figure captions, or table captions. Cross-references interrupt the flow of thought, and can actively interfere with the absorption of information. If the reader needs much extra information, rethink the structure of the section, and enrich the quality of the information. Do not let the cross-references overpower the message. A solution is to add a sentence to the end of the section to indicate where to find more information. + In running text, each paragraph should contain no more than a couple of links. Links should not occur in every paragraph, and they must not occur in titles, subheadings, or figure captions. Cross-references interrupt the flow of thought, and can actively interfere with the absorption of information. If the reader needs much extra information, rethink the structure of the section, and enrich the quality of the information. Do not let the cross-references overpower the message. A solution is to add a sentence to the end of the section to indicate where to find more information. diff --git a/en-US/Design.xml b/en-US/Design.xml index b772694..38c4e17 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -16,7 +16,7 @@ Capitalization The standard for all Red Hat technical documentation is title case for all headings and titles. - Table headings and procedure headings fall under this heading; standard title case capitalization rules apply. + Table titles and procedure headings fall into this category; standard title case capitalization rules apply. @@ -26,7 +26,7 @@ The currently accepted reference for determining title case is at https://titlecase.com/titlecase. - Use sentence case for captions, legends, diagram labels, and table column headers. + Use sentence case for figure captions, legends, diagram labels, and table column headers. They are not classified as titles. From a74a6487cfc4dbf3da27f7d3e426dd4a15f96f09 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Fri, 19 Jan 2024 17:26:25 +0000 Subject: [PATCH 37/79] Updates on referring to object names and using realistic usernames (#554) * Updates on referring to object names and using realistic usernames * Apply review comments --- en-US/Design.xml | 58 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 52 insertions(+), 6 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 38c4e17..9ca9f2a 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -16,7 +16,7 @@ Capitalization The standard for all Red Hat technical documentation is title case for all headings and titles. - Table titles and procedure headings fall into this category; standard title case capitalization rules apply. + Table titles and procedure titles fall into this category; standard title case capitalization rules apply. @@ -724,8 +724,8 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest - 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, Jerlene Paluch, Abby Quincy, Fricis Ritcher, and Jaya Lamont. - Huong is a department manager and needs read access to the accounting directory. Jerlene is the lead accountant and needs both read and write access. + 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. Choosing a Realistic Name @@ -743,6 +743,13 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest In examples or scenarios, you can use a person's name and then use a gender-specific pronoun to refer to that name. Vary the use of proper names in documentation. Use names that represent various ethnic backgrounds, genders, and locations. + + + + Include a diverse set of names in your examples to reflect the diversity of the real world. + For example, use gender-inclusive and culturally diverse names that suggest various backgrounds in examples to avoid implying that only certain groups have specific skills. + + @@ -750,10 +757,14 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest + - Include a diverse set of names in your examples to reflect the diversity of the real world. - For example, use male, female, and culturally diverse names that suggest various backgrounds in examples to avoid implying that only certain groups have specific skills. + When choosing names, also consider how those names might appear in email addresses, usernames, and similar contexts. + 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 jsmith@example.com. + However, for the name "Brian Strong", a corresponding email address of bstrong@example.com might not work so well (when read out, it sounds like "be strong"). + Consider also any implications for names in different languages. @@ -872,7 +883,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest - Place an object name before the noun that it modifies rather than after the noun. + In most cases, place an object name before the noun that it modifies rather than after the noun. @@ -899,6 +910,41 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest +
+ + 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. + + + + + + + + + + Example + Improvement + + + + + + + Log in as the admin user with the redhat password. + Log in as the admin user with redhat as the password. + + + + Define the backup_tmp variable with the /tmp value in the defaults/main.yml file. + Define the backup_tmp variable with a value of /tmp in the defaults/main.yml file. + + + + + + +
From 816aeef9c94bcfac0f766b862d772d4d2539a6db Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Thu, 1 Feb 2024 12:11:41 +0000 Subject: [PATCH 38/79] Updates for apostrophes and quotation marks (#557) * Updates for apostrophes and quotation marks * Updated list of punctuation marks --- en-US/Punctuation.xml | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 156241f..7c89f07 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -613,6 +613,9 @@ PLAY [Gather and display facts for managed nodes] **************************** For guidance on whether to use a possessive, refer to . + + Whether an apostrophe uses a straight character (the same as a straight single quotation mark) or a curly character is determined by considerations that include language, translation, and typography. +
@@ -750,7 +753,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - . , : ; ' " ( ) [ ] { } ! ? + . , : ; ' ‘ ’ " “ ” ( ) [ ] { } ! ? For all other characters, use the character name followed by the symbol in parentheses. @@ -819,7 +822,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - ' + ' or ’ Apostrophe @@ -874,8 +877,8 @@ PLAY [Gather and display facts for managed nodes] **************************** - " - Double quotation mark + " or “ ” + Double quotation marks @@ -959,8 +962,8 @@ PLAY [Gather and display facts for managed nodes] **************************** - ' - Single quotation mark + ' or ‘ ’ + Single quotation marks From 2b61ea84190d88152c57c6001cc420d8f21bd6da Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Fri, 2 Feb 2024 11:40:12 +0000 Subject: [PATCH 39/79] Updated guidance about titles (#559) * Updated guidance about titles * Change 'book' to 'publication' --- en-US/Book_Design.xml | 26 ++++++++++++------- en-US/Cross_references.xml | 2 +- en-US/Design.xml | 53 +++++++++++++++++++++++++++++++------- en-US/Language.xml | 2 +- en-US/Translation.xml | 2 +- 5 files changed, 63 insertions(+), 22 deletions(-) diff --git a/en-US/Book_Design.xml b/en-US/Book_Design.xml index ca49a26..6849ac1 100644 --- a/en-US/Book_Design.xml +++ b/en-US/Book_Design.xml @@ -4,7 +4,7 @@ %BOOK_ENTITIES; ]>
- Overall Book Design + Overall Publication Design This section describes a general approach to the overall layout and design of technical documentation. This design was developed specifically for technical documentation and might not suit content produced by other groups. @@ -34,6 +34,12 @@ Introductions + + + + Placement of headings + + @@ -48,10 +54,10 @@
Titles and Subtitles - The title should be a combination of the complete product name, its version, and the name of the book. For example, "Red Hat Satellite 5.6 Installation Guide", or "Red Hat Enterprise Linux 6 Deployment Guide". + The title should be a combination of the complete product name, its version, and the name of the publication. For example, "Red Hat Satellite 6.12 Installation Guide", or "Red Hat Enterprise Linux 9 Deployment Guide". - The subtitle should be a single, succinct phrase that describes the intent of the book; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 8 for all architectures". + The subtitle should be a single, succinct phrase that describes the intent of the publication; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 9 for All Architectures".
@@ -71,23 +77,23 @@ - A suitable abstract covers the high-level topics of the book, and is probably a good place to mention the audience. It should cover the following basics: + A suitable abstract covers the high-level topics of the publication, and is probably a good place to mention the audience. It should cover the following basics: - What: What is the purpose of the book or document? A brief summary, for example, "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API." + What: What is the purpose of the publication or document? A brief summary, for example, "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API." - How: How does the book convey its content? That is, is it task-based? Example-driven? A reference guide? For example, "The guide explains each API method and demonstrates examples of data models for input and output." + How: How does the publication convey its content? That is, is it task-based? Example-driven? A reference guide? For example, "The guide explains each API method and demonstrates examples of data models for input and output." - Why (and possibly Who): A basic rationale for why this book exists, and its audience (and elaborate on the target audience inside the book). For example, "This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." + Why (and possibly Who): A basic rationale for why this publication exists, and its audience (and elaborate on the target audience inside the publication). For example, "This publication provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." @@ -101,17 +107,17 @@ "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API. The guide explains each API method and demonstrates examples of data models for input and output. - This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." + This publication provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." - Update or modify each component according to the type of book that you are writing. + Update or modify each component according to the type of publication that you are writing.
Introductions - The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory (TM) tools, that Red Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to <product_name>" near the beginning of the book to introduce the reader to the product. Do not use "Introduction" to introduce the book; that is the task of the Abstract. A further benefit of this usage is that the same introduction can be used across various books to introduce the same product. + The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory tools, that Red Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to <product_name>" near the beginning of the publication to introduce the reader to the product. Do not use "Introduction" to introduce the publication; that is the task of the Abstract. A further benefit of this usage is that the same introduction can be used across various books to introduce the same product.
diff --git a/en-US/Cross_references.xml b/en-US/Cross_references.xml index 623cb63..4eac3d0 100644 --- a/en-US/Cross_references.xml +++ b/en-US/Cross_references.xml @@ -11,7 +11,7 @@ Formatting is not described in this section. - In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed book, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader. + In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed publication, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader.
The Additional Information Test diff --git a/en-US/Design.xml b/en-US/Design.xml index 9ca9f2a..f5af674 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -15,7 +15,8 @@ Capitalization - The standard for all Red Hat technical documentation is title case for all headings and titles. + The standard for technical documentation is title case for all headings and titles. + Table titles and procedure titles fall into this category; standard title case capitalization rules apply. @@ -32,7 +33,7 @@ Marketing and Brand Capitalization Guide - The Red Hat Marketing and Brand groups use sentence case for most titles and headings, with some exceptions, for example, when referencing an externally produced resource's title. + The Red Hat Marketing and Brand groups and some other groups use sentence case for most titles and headings, with some exceptions, for example, when referencing an externally produced resource's title. @@ -61,6 +62,9 @@ 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 "Installation Overview" or "The OpenShift Web Console." + + Avoid a title that consists of only one word. + @@ -85,6 +89,11 @@ Cluster Updates + + MetalLB + The MetalLB Component + + @@ -106,13 +115,39 @@ File Names, Commands, and Related Terms - When creating chapter and section titles, do not include file, command, or similar names, and do not include markup elements. + When creating chapter and section titles, do not include file, command, or similar names, and generally do not include markup elements. Instead, focus on the task at hand and introduce the required file and command names in the text. Including such objects in titles is generally considered poor technical writing practice. Depending on how your documentation is built and delivered, including these object types can result in unpredictable results and can even cause failed builds. +
+ + + + + + + Example + Improvement + + + + + + + Custom Domains and cert-manager Operators with ROSA + Custom Domains and Certificate Management Operators with ROSA + + + + + + + +
+
Documenting Fonts @@ -445,7 +480,7 @@ $ vi myFile.txt @@ -714,7 +749,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest
Using Extended User and Group Names - Sometimes, the recommended list of user and group names is too restrictive for the scope of a book or article. In such cases, the following extended model is acceptable. + Sometimes, the recommended list of user and group names is too restrictive for the scope of a publication or article. In such cases, the following extended model is acceptable. Using Realistic Usernames @@ -1338,9 +1373,9 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest
Citing Other Works - Referencing Other Books + Referencing Other Publications - When referencing another book, either internal or external to Red Hat, use the following format: + When referencing another publication, either internal or external to Red Hat, use the following format: @@ -1349,8 +1384,8 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest --> - -Book Title by First name Surname; Publisher. + +Publication Title by First name Surname; Publisher. diff --git a/en-US/Language.xml b/en-US/Language.xml index 9c05b08..384d379 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1628,7 +1628,7 @@ Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of ...), and very large values. - Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). + Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to publication sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate groups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 726b582..c59c81d 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -678,7 +678,7 @@ Entities can be helpful in some cases, but they are more of a hindrance when used for terms that need translation. Translators must compare the string with the built document to determine what the entity stands for. These entities might even be overlooked and not be translated at all. - To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities that are required to build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a book. Required entities vary by brand; only the following entities are required for a standard book: + To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities that are required to build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a publication. Required entities vary by brand; only the following entities are required for a standard publication: From e8141a20c08027f52a84e67cb26085f24e55846f Mon Sep 17 00:00:00 2001 From: Harpal Singh <52556240+harpasin@users.noreply.github.com> Date: Mon, 5 Feb 2024 15:41:15 +0530 Subject: [PATCH 40/79] Footnote update (#560) * adding ulink tag to a url * Replace an invalid URL --------- Co-authored-by: Julian Cable --- en-US/Design.xml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index f5af674..5a4c4ea 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -1418,8 +1418,9 @@ Publication Title by First name Surname; Publisher. - If the URL is excessively long or complex, create a link by using the title of the destination as a label, and put the actual URL in a footnote. For example: Refer to the Classification of Species - http://world-database-of-everything.com/en/classifcation_of_species/mammals.html + 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 Classification of Species + page for more information. From 5061af297674e99d4565611ec5e8147e3e768904 Mon Sep 17 00:00:00 2001 From: Alex Corcoles Date: Wed, 21 Feb 2024 17:57:27 +0000 Subject: [PATCH 41/79] fix(docs): add some build instructions (#562) * fix(docs): add some build instructions * feat: add build shortcut * Added small comment --------- Co-authored-by: julian-cable --- README.md | 16 ++++++++++++++++ build | 3 +++ 2 files changed, 19 insertions(+) create mode 100755 build diff --git a/README.md b/README.md index f07ab67..85a0d78 100644 --- a/README.md +++ b/README.md @@ -8,3 +8,19 @@ The Red Hat Style Guide and Word Usage Dictionary is a joint effort by vari It covers recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases. It is based on The IBM Style Guide but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions. + +Dependencies: + +``` +$ sudo dnf install publican +``` + +Also, follow the instructions at https://github.com/RedHatTraining/redhat-styleguide-xsl (access for Red Hat only) to build `publican-brand-redhat-*.noarch.rpm` and install that. + +To build: + +``` +$ publican build --langs=en-US --formats html +``` + +Generates `tmp/en-US/html/index.html`. diff --git a/build b/build new file mode 100755 index 0000000..b2efd20 --- /dev/null +++ b/build @@ -0,0 +1,3 @@ +#!/bin/sh + +publican build --langs en-US --formats html From 09d18cf9ee317f1a51c20acc9a3be3add0ac94c8 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Mon, 26 Feb 2024 12:12:54 +0000 Subject: [PATCH 42/79] Corrected some titles to use title case (#563) --- en-US/Punctuation.xml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 7c89f07..d4baa12 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -14,7 +14,7 @@ Current standards allow the use of a colon or semicolon in a range of different circumstances. Some of these are described in the following sections. - To relate clauses: + To Relate Clauses The following sentences show a connection or shared theme between two clauses, or use the second clause to reiterate or amplify the idea in the first clause: @@ -54,7 +54,7 @@ Try to limit your use of colons and semicolons. Separate sentences with a period if possible. - To introduce a series: + To Introduce a Series A colon is generally used before a series. @@ -142,7 +142,7 @@ - To introduce a list, command, code block, or procedure + To Introduce a List, Command, Code Block, or Procedure If a list, command, code block, or procedure immediately follows a single stem or introductory sentence, then end that sentence with a colon. @@ -265,7 +265,7 @@ PLAY [Gather and display facts for managed nodes] **************************** Commas - In compound sentences: + In Compound Sentences Use a comma to join clauses in a compound sentence, unless the clauses are short and have a similar theme. @@ -320,7 +320,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - With conjunctive adverbs: + With Conjunctive Adverbs When using a conjunctive adverb (such as however, therefore, otherwise, namely, for example, and so on) in a sentence, set it off with commas. @@ -342,7 +342,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - In adverbial clauses and phrases: + In Adverbial Clauses and Phrases If a dependent clause is restrictive (omission affects the meaning of the main clause), do not set it off with commas. If it is nonrestrictive (omission does not affect the main clause), set it off with commas: @@ -382,7 +382,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - In adjectival clauses or phrases: + In Adjectival Clauses or Phrases An adjectival clause that can be dropped without changing the meaning of the sentence is set off with commas. @@ -410,7 +410,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - With coordinate adjectives: + With Coordinate Adjectives Separate coordinate adjectives (two or more adjectives modifying the same noun) with commas. @@ -432,7 +432,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - With series and lists: + With Series and Lists Separate elements in a series of three or more with commas, including a comma before the conjunction if one is used. From 338068bd6dcf092648ff883cbb35d443e825f0ce Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Mon, 26 Feb 2024 16:35:29 +0000 Subject: [PATCH 43/79] Add release notes and update version info (#564) * Add release notes and update version info * Minor wording fix --- en-US/Book_Info.xml | 2 +- en-US/New.xml | 63 ++++++++++++++++++- ...le_Conventions_for_Writers_and_Editors.ent | 4 +- index.html | 6 +- 4 files changed, 67 insertions(+), 8 deletions(-) diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index e49ea58..f499499 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -8,7 +8,7 @@ Red Hat Technical Writing Style Guide - 6.1 + 6.2 1 diff --git a/en-US/New.xml b/en-US/New.xml index 5b08a1b..ff16b09 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -5,6 +5,66 @@ ]>
New in This Release + + Release 6.2 + Update in February 2024 to provide added or updated guidance and to address reported issues. + + + + Added guidance about line continuation for multiple operating systems. + Refer to . + + + Various updates to guidance about punctuation, including in lists and in tables. + Refer to . + + + Updated guidance about referring to special characters. + Refer to . + + + You can use the possessive form of the company name (Red Hat's) to refer to the company itself, not to any products or services. + Refer to . + + + Updated guidance about referring to named objects: usually as an adjective followed by a noun, but with some stated exceptions. + Refer to . + + + Updated guidance about using realistic usernames, and updated some of the username examples. + Refer to . + + + Added some clarifications about writing titles, and about the use of titles and captions with tables and images. + Refer to . + + + Added guidance about referring to Booleans. + Refer to . + + + Use "refer to" instead of "see" for references. + Refer to . + + + Updated terms that relate to 64-bit architecture: 64-bit ARM, 64-bit x86, AArch64, aarch64, AMD64, amd64, ARM64, arm64, Intel 64, x86_64. + Refer to . + + + Updated terms that relate to archive files: tar, tarball, untar, unzip, zip. + Refer to . + + + New or updated usage entries: lookup, refer to, screenshot, see. + Refer to . + + + Various other fixes. + + + + + Release 6.1 Update in August 2023 to provide added or updated guidance and to address reported issues. @@ -71,8 +131,7 @@ Refer to . - New or updated usage entries: application velocity, key ring, Metal-as-a-Service, OTP, smart card, systemwide, virtualized. - Refer to . + Improved formatting of spacing after tables and of displaying footnotes in dark mode. Various other fixes. diff --git a/en-US/Style_Conventions_for_Writers_and_Editors.ent b/en-US/Style_Conventions_for_Writers_and_Editors.ent index c062671..6f5d777 100644 --- a/en-US/Style_Conventions_for_Writers_and_Editors.ent +++ b/en-US/Style_Conventions_for_Writers_and_Editors.ent @@ -1,5 +1,5 @@ - + - \ No newline at end of file + \ No newline at end of file diff --git a/index.html b/index.html index 22cb2b9..59a6859 100644 --- a/index.html +++ b/index.html @@ -41,8 +41,8 @@

- - Red Hat Technical Writing Style Guide v6.1 + + Red Hat Technical Writing Style Guide v6.2

@@ -66,7 +66,7 @@

From 4ea55339c58a23ac1646beda6b2d4e6e85a39bae Mon Sep 17 00:00:00 2001 From: Harpal Singh <52556240+harpasin@users.noreply.github.com> Date: Tue, 15 Oct 2024 14:47:04 +0530 Subject: [PATCH 72/79] updating index page for v7.0 (#624) * updating index page for the latest version * Update index.html Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 8660fb1..241115c 100644 --- a/index.html +++ b/index.html @@ -41,8 +41,8 @@

- - Red Hat Technical Writing Style Guide v6.2 + + Red Hat Technical Writing Style Guide v7.0

From e18561d426534d7be7945e5e2bcd4790e5aa5c90 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Thu, 21 Nov 2024 17:32:27 +0000 Subject: [PATCH 73/79] Add dark mode enhancement to What's New (#626) --- en-US/New.xml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/en-US/New.xml b/en-US/New.xml index 8599bad..1e7fa81 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -7,7 +7,8 @@ New in This Release Release 7.0 - Major update in October 2024 with migration to a new hosting site, and extensive added and updated guidance. + Major update in November 2024, with extensive added and updated guidance. + Red Hat Technical Writing Style Guide - 7.0 + 7.1 1 diff --git a/en-US/Design.xml b/en-US/Design.xml index d56e377..1729dc0 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -1001,6 +1001,7 @@ telemetry-operator.v1.0.0 Telemetry Operator ... --> 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. @@ -1027,6 +1028,11 @@ telemetry-operator.v1.0.0 Telemetry Operator ... --> Define the backup_tmp variable with a value of /tmp in the defaults/main.yml file. + + The is:clear key is set to the false value. + The is:clear key is set to false. + + diff --git a/en-US/L.xml b/en-US/L.xml index 0b14e96..165ced1 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -222,6 +222,15 @@ + + + log out of + + + v. Write as three words. Use "log out of", not "log out from". For example, "to log out of the system". + + + look at diff --git a/en-US/New.xml b/en-US/New.xml index 1e7fa81..aebf5cd 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -5,6 +5,37 @@ ]>
New in This Release + + Release 7.1 + Maintenance release in April 2025, with some added and updated guidance. + + + + Added an entry for "log out of", to use in preference to "log out from". + Refer to . + + + Added an entry for "print queue", to use in preference to "printer queue". + Refer to . + + + Changed to use hyphenation for "greater-than" and "less-than", to refer to these characters. + Refer to . + + + Updated guidance to not require a noun with object names in all cases. + Refer to . + + + Updated guidance about the number of items in a bulleted list to allow fewer items in specific cases. + Refer to . + + + Various other fixes. + + + + Release 7.0 Major update in November 2024, with extensive added and updated guidance. @@ -84,9 +115,6 @@ Various other fixes. - - - diff --git a/en-US/P.xml b/en-US/P.xml index 9d1c4cf..3c89e9e 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -208,6 +208,16 @@ + + + print queue + + + n. Use "print queue", not "printer queue", to refer to a list of print jobs that are sent to a printer. + + + + proof of concept diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index bb62e9d..9dee574 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -559,26 +559,45 @@ PLAY [Gather and display facts for managed nodes] **************************** Correct Examples of the Use of Punctuation with Quotation Marks - - For bind mounts, add "bind" and set fstype to "none". - - - Login successful. - ...output omitted... - Using project "default". - - - As in the previous image, the title of the web page is "OpenShift 3 Etherpad". - - - In the program segment, ensure that the value is X'FF'. - - - - Julius Caesar said, "I came. I saw. I conquered." - + + + + + For bind mounts, add "bind" and set fstype to "none". + + + + + + +Login successful. +...output omitted... +Using project "default". + + + + + + + The title of the web page is "OpenShift 3 Etherpad". + + + + + + In the program segment, ensure that the value is X'FF'. + + + + + + Julius Caesar said, "I came. I saw. I conquered." + + + + + +
@@ -762,7 +781,7 @@ PLAY [Gather and display facts for managed nodes] **************************** For all other characters, use the character name followed by the symbol in parentheses. - For special character names that include a noun such as "sign", "symbol", or "character", provide the character name, the noun that describes the symbol, and then the symbol in parentheses, for example "the greater than symbol (>)". + For special character names that include a noun such as "sign", "symbol", or "character", provide the character name, the noun that describes the symbol, and then the symbol in parentheses, for example "the greater-than symbol (>)". For special character names that do not include such nouns, provide the character name and the symbol in parentheses, for example "a forward slash (/)". You can end a sentence with the symbol in parentheses. @@ -923,7 +942,7 @@ PLAY [Gather and display facts for managed nodes] **************************** > - Greater than symbol + Greater-than symbol @@ -933,7 +952,7 @@ PLAY [Gather and display facts for managed nodes] **************************** < - Less than symbol + Less-than symbol diff --git a/en-US/Style_Conventions_for_Writers_and_Editors.ent b/en-US/Style_Conventions_for_Writers_and_Editors.ent index 6f5d777..6320711 100644 --- a/en-US/Style_Conventions_for_Writers_and_Editors.ent +++ b/en-US/Style_Conventions_for_Writers_and_Editors.ent @@ -1,5 +1,5 @@ - + - \ No newline at end of file + \ No newline at end of file diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 1637373..c7c170e 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -31,7 +31,9 @@ Bulleted lists - Use this list type for three or more entries where order is not important. + Use this list type when the order of items is not important. + In most cases, a bulleted list should have three or more entries. + In limited cases, specific publications might choose instead to allow fewer entries in a list. Titles are optional. @@ -87,7 +89,7 @@ Nested lists. - Nested lists themselves can use the attribute if they fall outside the bounds of these recommendations. + Nested list items themselves can use the attribute if they fall outside the bounds of these recommendations. From 9f06c35a39fb9c08a075047ad20766b475bd90b0 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Mon, 12 May 2025 14:32:34 +0100 Subject: [PATCH 75/79] A further round of maintenance updates for the 7.1 release (#641) * A further round of maintenance updates for the 7.1 release * Add dollar sign * Minor fix * Further fix --- en-US/A.xml | 140 ++++++++++++++++++++++++++++-------------- en-US/B.xml | 18 +++--- en-US/C.xml | 30 ++++++--- en-US/D.xml | 14 ++--- en-US/Design.xml | 3 +- en-US/E.xml | 26 +++++--- en-US/G.xml | 14 +++++ en-US/I.xml | 20 +++--- en-US/New.xml | 30 ++++++++- en-US/Punctuation.xml | 7 ++- en-US/S.xml | 18 +++--- 11 files changed, 218 insertions(+), 102 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index 72791ed..044cebd 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -14,6 +14,44 @@ + + + AArch64, aarch64 + + + n. A 64-bit version of the ARM architecture. + Use this term when referring to operating systems and server instances, for example Red Hat Enterprise Linux, Fedora, CoreOS, and other Linux distributions. + + + 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. + It can be styled as code (monospace font or a code-styled block) when referring to code. + + + 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. + + + Examples: + + + + + When running Red Hat Enterprise Linux with an AArch64 system, run the following commands: + + + + + Specify the system architecture of your cluster, such as x86_64 or aarch64. + + + + + Refer also to , , , , , and . + + + + above @@ -102,44 +140,6 @@ - - - AArch64, aarch64 - - - n. A 64-bit version of the ARM architecture. - Use this term when referring to operating systems and server instances, for example Red Hat Enterprise Linux, Fedora, CoreOS, and other Linux distributions. - - - 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. - It can be styled as code (monospace font or a code-styled block) when referring to code. - - - 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. - - - Examples: - - - - - When running Red Hat Enterprise Linux with an AArch64 system, run the following commands: - - - - - Specify the system architecture of your cluster, such as x86_64 or aarch64. - - - - - Refer also to , , , , , and . - - - - AMD64, amd64 @@ -299,24 +299,21 @@ - - as well as + + artificial intelligence (AI) - Not interchangeable with "and". - "As well as" used in a series places more emphasis on the items preceding it, whereas "and" places equal weight on all items in the series. - For example, "We sell kitchen electronics and china, as well as some gourmet foods." - But "We sell kitchen electronics, china, and silverware." + 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. - as-a-Service + as-a-Service - Some as-a-Service acronyms overlap. + Some "as-a-Service" acronyms overlap. To avoid confusion, always spell out the full term on first use. @@ -412,7 +409,43 @@ - + + + as Code + + + 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. + + + Examples: + + + + + Configuration as Code (CaC) + + + + + + Infrastructure as Code (IaC) + + + + + + Policy as Code (PaC) + + + + + + + + as long as @@ -423,6 +456,19 @@ + + + as well as + + + Not interchangeable with "and". + "As well as" used in a series places more emphasis on the items preceding it, whereas "and" places equal weight on all items in the series. + For example, "We sell kitchen electronics and china, as well as some gourmet foods." + But "We sell kitchen electronics, china, and silverware." + + + + ATM diff --git a/en-US/B.xml b/en-US/B.xml index c09cfd3..db17543 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -24,6 +24,15 @@ + + + backtrace + + + n. "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback", possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. + + + backup, back up @@ -59,15 +68,6 @@ - - - backtrace - - - n. "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback", possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. - - - backwards compatible diff --git a/en-US/C.xml b/en-US/C.xml index 4084c54..478d972 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -248,6 +248,17 @@ + + code base + + + n. Two words. + Do not use "codebase", outside the specific context of codebase.com. + + + + + colocate, colocation @@ -388,16 +399,7 @@ - - Containers-as-a-Service - - - The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. Refer also to . - - - - container-based @@ -417,6 +419,16 @@ + + + Containers-as-a-Service + + + The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. Refer also to . + + + + continuous delivery (CD) diff --git a/en-US/D.xml b/en-US/D.xml index bb8f48e..adbd557 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -218,23 +218,23 @@ Describe, rather than label. - - Disk Druid + + disk, disc - Correct. Do not use "Disk druid", "disk druid", or "diskdruid". This is a partitioning tool that is incorporated into Red Hat Enterprise Linux. + Use "compact disc" or "hard disk". + - - disk, disc + + Disk Druid - Use "compact disc" or "hard disk". + Correct. Do not use "Disk druid", "disk druid", or "diskdruid". This is a partitioning tool that is incorporated into Red Hat Enterprise Linux. - diff --git a/en-US/Design.xml b/en-US/Design.xml index 1729dc0..764925d 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -501,7 +501,8 @@ $ vi myFile.txt --> - You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required. + 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. diff --git a/en-US/E.xml b/en-US/E.xml index bf7cb4f..7948e7a 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -6,6 +6,17 @@ E + + earlier + + + Use to refer to earlier releases of products. Do not use "older" or related terms. + Refer also to . + + + + + ebook, e-commerce, e-learning, email @@ -15,22 +26,21 @@ - - e.g. + + edge - Red Hat technical documentation always expands these abbreviations. Write out "for example". + Describes network elements outside the gateway and server-side or cloud-side functions (for example, "an edge device"). + Do not refer to "the edge" without qualifying it; define the first instance (for example, "the edge of the network"). - - - earlier + + e.g. - Use to refer to earlier releases of products. Do not use "older" or related terms. - Refer also to . + Red Hat technical documentation always expands these abbreviations. Write out "for example". diff --git a/en-US/G.xml b/en-US/G.xml index 9faef8e..9cf59ac 100644 --- a/en-US/G.xml +++ b/en-US/G.xml @@ -102,6 +102,20 @@ + + + generative AI, gen AI + + + Unless clarity requires it or the concept is being introduced or explained, "generative artificial intelligence" does not have to be spelled out on first use; the abbreviation "gen AI" is understood and suffices. + When spelling it out, do not capitalize the term. + + + Note: Because generative AI is a relatively new technology concept, the term and how it is applied is evolving, so this guidance might change accordingly. + + + + GEO, geo diff --git a/en-US/I.xml b/en-US/I.xml index a9ec824..881a55b 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -25,16 +25,6 @@ - - - Infrastructure as Code (IaC) - - - Based on search volume, the nonhyphenated full term and camel-case acronym are preferred. Use uppercase "I" and "C". - - - - IBM Z @@ -96,6 +86,16 @@ + + + Infrastructure as Code (IaC) + + + Based on search volume, the nonhyphenated full term and camel-case acronym are preferred. Use uppercase "I" and "C". + + + + inline diff --git a/en-US/New.xml b/en-US/New.xml index aebf5cd..739deae 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -7,9 +7,29 @@ New in This Release Release 7.1 - Maintenance release in April 2025, with some added and updated guidance. + Maintenance release in May 2025, with some added and updated guidance. + + Added an entry for "artificial intelligence (AI)". + Refer to . + + + Added an entry for "as Code". + Refer to . + + + Added an entry for "code base", to use in preference to "codebase". + Refer to . + + + Added an entry for "edge". + Refer to . + + + Added an entry for "generative AI, gen AI". + Refer to . + Added an entry for "log out of", to use in preference to "log out from". Refer to . @@ -18,6 +38,14 @@ Added an entry for "print queue", to use in preference to "printer queue". Refer to . + + Changed guidance to not use manual line indentation for the second and subsequent lines of commands. + Refer to . + + + Added the dollar sign to the table of punctuation marks and special characters. + Refer to . + Changed to use hyphenation for "greater-than" and "less-than", to refer to these characters. Refer to . diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 9dee574..4c3a0fe 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -800,7 +800,7 @@ Using project "default". Referring to Special Characters - When a regular user starts a shell, the prompt includes an ending dollar character ($). + When a regular user starts a shell, the prompt includes an ending dollar sign ($). Use the pipe character (|) to send the output of one program to the input of another program. @@ -904,6 +904,11 @@ Using project "default". , Comma + + + $ + Dollar sign + " or “ ” diff --git a/en-US/S.xml b/en-US/S.xml index fc87234..38e3f54 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -546,6 +546,15 @@ + + source + + + v. In addition to the generic use of this term as a noun and verb, in +a programming and technical sense, it also means "Run the source command against the named file." + + + Source-Navigator™ @@ -556,15 +565,6 @@ - - source - - - v. In addition to the generic use of this term as a noun and verb, in -a programming and technical sense, it also means "Run the source command against the named file." - - - space From ba3f1854046c4dad3724da1d1dd6c8e6ddc2529a Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Mon, 2 Jun 2025 11:29:48 +0100 Subject: [PATCH 76/79] Jcable/allow object class (#643) * Update guidance for 'allow' * Add guidance for naming object classes * Implement feedback * Minor restructure and update release notes --- en-US/Design.xml | 72 ++++++++++++++++++++++++++++++++++++++++++++++ en-US/Language.xml | 36 ++++++++++++++++++++++- en-US/New.xml | 10 ++++++- 3 files changed, 116 insertions(+), 2 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 764925d..7411bd1 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -1042,6 +1042,78 @@ telemetry-operator.v1.0.0 Telemetry Operator ... -->

+
+ Naming of Object Classes + + When naming an object, consider the impact of its name when writing about the object. + Avoid duplication, alliteration, or long names. + In cases where including the class in an object name helps to provide clarity, avoid including the object's class in the last part of its name. + This approach avoids repetition when writing about the object where the noun that follows the object name indicates its class. + + + + + + + + + + Example + Improvement + + + + + + + + The user that you use to log in is the remote-user user. + Log in as the user-remote user. + + + + Go to the local-project project. + Go to the proj-local project. + + + + Use the base-layer layer of the container. + Use the base-image layer of the container. + + + + Create the instance in the prod-environment environment. + Create the instance in the prod environment. + + + + + Use the oc process --parameters command to view the parameter of the roster-template template. + Use the oc process --parameters command to view the parameter of the roster template. + + + + Create the namesList variable in the my-file file as part of the managedCluster cluster. + Create the namesList variable in the file-test file as part of the cluster-managed cluster. + + + + Verify that the famous-quotes-pvc PVC (Persistent Volume Claim) is successfully created. + Verify that the famous-quotes PVC (Persistent Volume Claim) is successfully created. + + + + + + + +
+ +
diff --git a/en-US/Language.xml b/en-US/Language.xml index f27ce62..ac8a695 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -943,9 +943,26 @@ +
+ Use of "Allow" - Avoid stating that a product or feature allows the user to do something. Focus instead on what the user does. + Except when referring specifically to permission, avoid stating that a product or feature allows the user to do something. + + + Valid Uses of "Allow" to Refer to Permission + + + Some open source licenses allow code to be reused in proprietary products. + + + You can configure the sudo command to allow specific users to run any command as some other user. + + + + In cases that do not refer to permission, whenever possible, focus instead on what the user, service, or agent does, or replace "allow" with a different verb, such as "enable". + + @@ -970,6 +987,21 @@ You can use collections to separate core Ansible code updates from updates to modules and plug-ins. + + The system menu allows you to switch network and VPN connections on or off. + From the system menu, you can switch network and VPN connections on or off. + + + + The workspace selector displays active workspaces and allows you to switch between workspaces. + The workspace selector displays active workspaces and enables you to switch between workspaces. + + + @@ -980,6 +1012,8 @@ Report an issue + +
diff --git a/en-US/New.xml b/en-US/New.xml index 739deae..914c2b0 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -7,7 +7,7 @@ New in This Release Release 7.1 - Maintenance release in May 2025, with some added and updated guidance. + Maintenance release in June 2025, with some added and updated guidance. @@ -42,6 +42,14 @@ Changed guidance to not use manual line indentation for the second and subsequent lines of commands. Refer to . + + Added guidance on the use of "allow". + Refer to . + + + Added guidance on the naming of object classes". + Refer to . + Added the dollar sign to the table of punctuation marks and special characters. Refer to . From 60c00213b84aac24fc57eb40100d0a51e206cb80 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Mon, 2 Jun 2025 13:14:19 +0100 Subject: [PATCH 77/79] Minor typing fix (#644) --- en-US/New.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/New.xml b/en-US/New.xml index 914c2b0..fd8b2ee 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -47,7 +47,7 @@ Refer to . - Added guidance on the naming of object classes". + Added guidance on the naming of object classes. Refer to . From 3fe15f759ff2624fcf8bc1a6d54b4353aefbaee4 Mon Sep 17 00:00:00 2001 From: julian-cable Date: Tue, 3 Jun 2025 12:06:27 +0100 Subject: [PATCH 78/79] Minor fixes for 'referring to' section --- en-US/New.xml | 2 +- en-US/Punctuation.xml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/en-US/New.xml b/en-US/New.xml index fd8b2ee..0e40fb1 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -168,7 +168,7 @@ Updated guidance about referring to special characters. - Refer to . + Refer to . You can use the possessive form of the company name (Red Hat's) to refer to the company itself, not to any products or services. diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 4c3a0fe..38068ca 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -771,7 +771,7 @@ Using project "default".
-
+
Referring to Punctuation Marks and Special Characters To refer to a punctuation mark or special character, use its name alone if it is one of the following standard characters: @@ -800,7 +800,7 @@ Using project "default". Referring to Special Characters - When a regular user starts a shell, the prompt includes an ending dollar sign ($). + When a regular user starts a shell, the prompt includes an ending dollar sign ($). Use the pipe character (|) to send the output of one program to the input of another program. From f43f598bbdd37826d89baa4302f52f82db9f7fb9 Mon Sep 17 00:00:00 2001 From: Harpal Singh Date: Wed, 4 Jun 2025 12:27:09 +0530 Subject: [PATCH 79/79] updating hompage version --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 241115c..eb872be 100644 --- a/index.html +++ b/index.html @@ -42,7 +42,7 @@

- Red Hat Technical Writing Style Guide v7.0 + Red Hat Technical Writing Style Guide v7.1