From c59529a9a43d5ff3afc518e060e2a93af163f750 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 29 Sep 2022 18:19:40 +0100 Subject: [PATCH 1/7] Adding snippet guidance Part 1 --- en-US/Grammar.xml | 270 ++++++++++++++++++++++++++++++++++++++++++++- en-US/Language.xml | 80 ++++++++++++++ 2 files changed, 347 insertions(+), 3 deletions(-) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 88cc7be..20b18eb 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -107,6 +107,44 @@ + +
+ Countable Nouns + + For nouns that are not countable, it is correct to use "less" and "amount", for example "less memory" or "the required amount of memory". + For nouns that are countable, use "fewer" instead of "less", and use "number" instead of "amount". + + + + + + + + + Example + Improvement + + + + + + + This passphrase configuration can improve security by providing less opportunities for someone else to see you type the passphrase. + This passphrase configuration can improve security by providing fewer opportunities for someone else to see you type the passphrase. + + + + Vim has fast, efficient keystrokes to delete an exact amount of words, lines, sentences, or paragraphs. + Vim has fast, efficient keystrokes to delete an exact number of words, lines, sentences, or paragraphs. + + + + + + + +
+
Using Who, Whom, That, and Which Correctly @@ -416,6 +454,187 @@ + + + Causative Verbs + + Avoid the construction "have something happen". Rewrite to replace "have" with a verb that describes the actual action. + + + + + + + + + + + Example + Improvement + + + + + + + The latter connection has no devices assigned. + No devices are assigned to the latter connection. + + + + To have the changes take effect … + To apply the changes … + + + + + + + +
+ + + + Condition and Action + + A condition should precede an action. A clause that explains "why", or for what purpose, should come before a statement of what the action is or how it is done. + + + + + + + + + + + Example + Improvement + + + + + + + Divide the storage devices into smaller chunks to create a partition. + To create a partition, divide the storage devices into smaller chunks. + + + + + + + +
+ + + + Either, Or + + Use the "either x ... or y" construction only to refer to a choice between two options, not for three or more options. + + + + + + + + + + + Example + Improvement + + + + + + + Scale up by adding more resources, with either more memory, CPU, disk space, or other resources. + Scale up by adding more resources, with more memory, CPU, disk space, or other resources. + + + + + + + +
+ + + + Following + + Use "following" with a noun. + In a quiz question, "the following" is often superfluous. + + + + + + + + + + + Example + Improvement + + + + + + + Non-privileged users can use the role to configure the following: + Non-privileged users can use the role to configure the following interfaces: + + + + Which two of the following statements describe the benefits of Linux? + Which two statements describe the benefits of Linux? + + + + + + + +
+ + + + If, Then + + Follow an "if" statement with a "then" statement. + + + + + + + + + + + Example + Improvement + + + + + + + If one service is started, the other is started as well. + If one service is started, then the other is started as well. + + + + + + + +
+ "That" in Clauses @@ -606,11 +825,56 @@ Split contractions and abbreviations into separate paragraphs. -->
-
- Gender References +
+ 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 far less awkward 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 "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. + Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward 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 "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. + + 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. + + + + + + + + + + Example + Improvement + + + + + + + An engineer must be trained on the equipment that he services. + Engineers must be trained on the equipment that they service. + + + + In the web console, we can restart or shut down the system. + In the web console, you can restart or shut down the system. + + + + We recommend that you generate a service account for each microservice in your project. + Red Hat recommends that you generate a service account for each microservice in your project. + + + + + + + +
diff --git a/en-US/Language.xml b/en-US/Language.xml index e75460f..198f4b6 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -946,6 +946,86 @@ Numbers (move from N entry) -->
+ +
+ Avoiding "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. + + + + + + + + + Example + Improvement + + + + + + + Mounting a device is relatively simple. + Identify the device for mounting, ensure that the mount point exists, and mount the device on the mount point. + + + + Kubernetes is an orchestration service that makes it easier to deploy, manage, and scale container-based applications across a cluster of container hosts. + + + Option 1: Kubernetes is an orchestration service that deploys, manages, and scales container-based applications across a cluster of container hosts. + + + Option 2: Kubernetes is an orchestration service that makes it easier than manual container management. Kubernetes deploys, manages, and scales container-based applications across a cluster of container hosts. + + + + + + + + + +
+ +
+ + +
+ Avoiding Redundant Words + + Avoid the words "actually", "just", "really", "simply" and "very". They are filler words that add no value to a sentence. + + + + + + + + + Example + Improvement + + + + + + + Remote users can connect to network resources simply by authenticating to their local machine. + Remote users can connect to network resources by authenticating to their local machine. + + + + + + + +
+ +
+
Avoiding Ambiguities From 5cf40abc0bd40a345309ef2ccc52d24757109c8e Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 6 Oct 2022 15:26:10 +0100 Subject: [PATCH 2/7] Further enhancements to 6.0 --- en-US/Book_Info.xml | 2 +- en-US/Translation.xml | 67 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 1 deletion(-) diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index 2d513ce..ad9f2e2 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -8,7 +8,7 @@ Red Hat Technical Writing Style Guide - 5.1 + 6.0 1 diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 7800861..cb868dc 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -116,6 +116,9 @@ The following discussion provides some initial insight into using lists correctly. See 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. + @@ -180,6 +183,70 @@
+ + For a lead-in sentence that introduces a list, use a complete sentence. A lead-in that is a sentence fragment is hard to translate into other languages. + + + + + + + + + Example + Improvement + + + + + + + + Non-privileged users can use the role to configure: + + + + + Interface 1 + + + + + + Interface 2 + + + + + + + + Non-privileged users can use the role to configure the following interfaces: + + + + + Interface 1 + + + + + + Interface 2 + + + + + + + + + + + + + +
From 8c58dca92babac24311a9f3cc4b0d2286964de09 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 14 Oct 2022 12:30:29 +0100 Subject: [PATCH 3/7] Fixes to implement feedback --- en-US/Grammar.xml | 17 +++++---- en-US/Language.xml | 82 +++++++++++++++++++++++++------------------ en-US/Translation.xml | 2 +- 3 files changed, 57 insertions(+), 44 deletions(-) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 20b18eb..b9d7745 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -493,8 +493,7 @@ - - + - Either, Or + The Either-Or Construction Use the "either x ... or y" construction only to refer to a choice between two options, not for three or more options. @@ -563,7 +562,7 @@ - Following + Use of Following Use "following" with a noun. In a quiz question, "the following" is often superfluous. @@ -603,9 +602,9 @@ - If, Then + The If-Then Construction - Follow an "if" statement with a "then" statement. + Generally, follow an "if" statement with a "then" statement. @@ -637,7 +636,7 @@ - "That" in Clauses + That in Clauses Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English. @@ -831,7 +830,7 @@ Split contractions and abbreviations into separate paragraphs. --> Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward 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 "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. + 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. Using "one" is far too formal. Do not use "it" to refer to a person. Avoid first person "I, we, our". Use second person "you" whenever possible. diff --git a/en-US/Language.xml b/en-US/Language.xml index 198f4b6..7c52c5c 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -946,11 +946,11 @@ Numbers (move from N entry) --> - -
- Avoiding "Easy" + +
+ Avoiding Redundant Words - 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 redundant words, such as "actually", "just", "really", "simply" and "very". They are filler words that add no value to a sentence. @@ -967,20 +967,18 @@ Numbers (move from N entry) --> - Mounting a device is relatively simple. - Identify the device for mounting, ensure that the mount point exists, and mount the device on the mount point. + Remote users can connect to network resources simply by authenticating to their local machine. + Remote users can connect to network resources by authenticating to their local machine. - Kubernetes is an orchestration service that makes it easier to deploy, manage, and scale container-based applications across a cluster of container hosts. - - - Option 1: Kubernetes is an orchestration service that deploys, manages, and scales container-based applications across a cluster of container hosts. - - - Option 2: Kubernetes is an orchestration service that makes it easier than manual container management. Kubernetes deploys, manages, and scales container-based applications across a cluster of container hosts. - - + Any settings that are changed with this command revert back to their original settings when the daemon restarts. + Any settings that are changed with this command revert to their original settings when the daemon restarts. + + + + 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. @@ -992,12 +990,17 @@ Numbers (move from N entry) --> - -
- Avoiding Redundant Words - - Avoid the words "actually", "just", "really", "simply" and "very". They are filler words that add no value to a sentence. - + +
+ Avoiding Ambiguities + + + + 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. +
@@ -1013,8 +1016,8 @@ Numbers (move from N entry) --> - Remote users can connect to network resources simply by authenticating to their local machine. - Remote users can connect to network resources by authenticating to their local machine. + 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. @@ -1024,18 +1027,15 @@ Numbers (move from N entry) -->
-
- - -
- Avoiding Ambiguities - + - - Capitalizing Proper Nouns + + + + Avoiding "Easy" - 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. + 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. @@ -1052,8 +1052,22 @@ Numbers (move from N entry) --> - 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. + Mounting a device is relatively simple. + Identify the device for mounting, ensure that the mount point exists, and mount the device on the mount point. + (Omit the first sentence.) + To mount a device, identify the device for mounting, ensure that the mount point exists, and mount the device on the mount point. + + + + Kubernetes is an orchestration service that makes it easier to deploy, manage, and scale container-based applications across a cluster of container hosts. + + + Option 1: Kubernetes is an orchestration service that deploys, manages, and scales container-based applications across a cluster of container hosts. + + + Option 2: Kubernetes is an orchestration service that makes it easier than manual container management to deploy, manage, and scale container-based applications across a cluster of container hosts. + + diff --git a/en-US/Translation.xml b/en-US/Translation.xml index cb868dc..7f652cf 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -184,7 +184,7 @@
- For a lead-in sentence that introduces a list, use a complete sentence. A lead-in that is a sentence fragment is hard to translate into other languages. + For a lead-in sentence that introduces a list, use a complete sentence. A lead-in that is a sentence fragment can be difficult to translate into other languages. From 09326670e015553aaf806e5401a67be2c5afb1b8 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 14 Oct 2022 16:41:39 +0100 Subject: [PATCH 4/7] Further fixes --- en-US/Grammar.xml | 6 +++--- en-US/Language.xml | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index b9d7745..5cf56e6 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -549,8 +549,8 @@ - Scale up by adding more resources, with either more memory, CPU, disk space, or other resources. - Scale up by adding more resources, with more memory, CPU, disk space, or other resources. + Scale up by adding more resources, with either more memory, CPUs, or disk space. + Scale up by adding more resources, such as memory, CPUs, or disk space. @@ -636,7 +636,7 @@ - That in Clauses + Including That in Clauses Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English. diff --git a/en-US/Language.xml b/en-US/Language.xml index 7c52c5c..9d5b8ed 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -950,7 +950,7 @@ Numbers (move from N entry) -->
Avoiding Redundant Words - Avoid redundant words, such as "actually", "just", "really", "simply" and "very". They are 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.
@@ -1032,7 +1032,7 @@ Numbers (move from N entry) --> - Avoiding "Easy" + 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. From 0b992118b97513c99a14dc633e82ace09240725f Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Mon, 17 Oct 2022 11:53:15 +0100 Subject: [PATCH 5/7] Update to implement Fernando's feedback --- en-US/Language.xml | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/en-US/Language.xml b/en-US/Language.xml index 9d5b8ed..492d784 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1059,15 +1059,8 @@ Numbers (move from N entry) --> - Kubernetes is an orchestration service that makes it easier to deploy, manage, and scale container-based applications across a cluster of container hosts. - - - Option 1: Kubernetes is an orchestration service that deploys, manages, and scales container-based applications across a cluster of container hosts. - - - Option 2: Kubernetes is an orchestration service that makes it easier than manual container management to deploy, manage, and scale container-based applications across a cluster of container hosts. - - + Kubernetes is an open source system that makes it easy to manage containerized applications across multiple hosts. + Kubernetes is an open source system to manage containerized applications across multiple hosts. From 4d14415edf068a8159009b5e6c366575c1feca87 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 20 Oct 2022 18:38:46 +0100 Subject: [PATCH 6/7] Adding addressing of issue 399 to the scope --- en-US/Grammar.xml | 48 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 5cf56e6..878d7ca 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -667,6 +667,54 @@
+ + + + Use of This That These Those + + Use "this", "that", "these", or "those" followed by a noun. + Doing so improves clarity for readers whose primary language is not English, and improves accuracy of translation into other languages where these words differ based on the gender of the noun that they refer to. + + + + + + + + + + + Example + Improvement + + + + + + + This causes SSH to lose the recorded identities of the remote systems. + + + Option 1: This action causes SSH to lose the recorded identities of the remote systems. + + + Option 2: Consequently, SSH loses the recorded identities of the remote systems. + + + + + + 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. + + + + + + + +
+ Verbosity From 7c25c0e738b27bba126aa0004895da2a9691672a Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Tue, 25 Oct 2022 11:44:46 +0100 Subject: [PATCH 7/7] Implemented review comments --- en-US/Grammar.xml | 11 ++++++----- en-US/Language.xml | 4 ++++ 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 77e8de8..6b43149 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -635,8 +635,8 @@ - If one service is started, the other is started as well. - If one service is started, then the other is started as well. + If one service is started, the other is also started. + If one service is started, then the other is also started. @@ -650,7 +650,8 @@ Including That in Clauses - Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English. + Include the word "that" in clauses unless it results in writing that is too formal or stilted. + Including the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English. @@ -892,10 +893,10 @@ 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 far less awkward 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. Using "one" is far too formal. Do not use "it" to refer to a person. + 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. Avoid first person "I, we, our". Use second person "you" whenever possible. diff --git a/en-US/Language.xml b/en-US/Language.xml index b5d4249..62e23f8 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1006,6 +1006,10 @@ 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". + +