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/Grammar.xml b/en-US/Grammar.xml index c3b1d36..2eb37eb 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 @@ -428,11 +466,192 @@ + + + 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 … + + + + + + + +
+ + + + + + 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. + + + + + + + + + + + Example + Improvement + + + + + + + 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. + + + + + + + +
+ + + + Use of 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? + + + + + + + +
+ + + + The If-Then Construction + + Generally, follow an "if" statement with a "then" statement. + + + + + + + + + + + Example + Improvement + + + + + + + If one service is started, the other is also started. + If one service is started, then the other is also started. + + + + + + + +
+ - "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. + 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. @@ -461,6 +680,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 @@ -623,11 +890,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 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. + - 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 2c10804..92b3568 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1000,6 +1000,54 @@
+ +
+ 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. + + + 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". + + + + + + + + + + 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. + + + + 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. + + + + + + + +
+ +
+
Avoiding Ambiguities @@ -1040,6 +1088,49 @@ + + + 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. + + + + + + + + + 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. + (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 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. + + + + + + + +
+ + + + Homographic Verbs diff --git a/en-US/Translation.xml b/en-US/Translation.xml index efbcffd..0093639 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -112,6 +112,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. + @@ -176,6 +179,70 @@
+ + 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. + + + + + + + + + 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 + + + + + + + + + + + + + +
Make items in a list grammatically parallel.