From c8fc7bbd2d80eb2c25adf00a781a8f5ed07857f3 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Tue, 14 Nov 2023 17:42:52 +0000 Subject: [PATCH 1/6] Updated guidance for punctuation and special characters --- en-US/Grammar.xml | 19 ++++++ en-US/Punctuation.xml | 134 +++++++++++++++++++++++++++++++++++++++++- en-US/Translation.xml | 2 +- 3 files changed, 153 insertions(+), 2 deletions(-) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 79bdd98..69e54a0 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..f2441cb 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -625,8 +625,127 @@ 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: @@ -635,6 +754,7 @@ PLAY [Gather and display facts for managed nodes] **************************** For all other characters, use the character name followed by the symbol in parentheses. + When referring to a symbol in parentheses, the symbol name comes after any noun that describes the symbol. Do not use the symbol on its own. @@ -647,6 +767,18 @@ PLAY [Gather and display facts for managed nodes] **************************** The path contains the library qualifier in braces. + + Referring to Special Characters + + + To add a node, click the plus character (+). + + + Use the pipe character (|) to send the output of one program to the input of another program. + + + The hyphen after the greater-than sign (>) indicates that a newline character (\n) is not added to the end of the variable. + For more details, see the IBM Style Guide. diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 9801c5e..d3a44c2 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -323,7 +323,7 @@
-
Punctuation in Lists +
Punctuation in Lists For each item in a list, start with either a complete sentence or a sentence fragment. From 4cd44547be777ced466a4bfaa0f34edff2bfe13c Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Mon, 20 Nov 2023 18:04:35 +0000 Subject: [PATCH 2/6] Enhanced guidance about punctuation in lists --- en-US/Translation.xml | 66 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 5 deletions(-) diff --git a/en-US/Translation.xml b/en-US/Translation.xml index d3a44c2..ff6f756 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -327,6 +327,13 @@ 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. @@ -365,31 +372,80 @@ Example: - Which resource type does the Operator Lifecycle Manager use to store information about installed operators? + Kubernetes networking provides the following capabilities: - Operator group + 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 without a subject and 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: + + - Catalog source + Initializing or migrating a database - Install plan + Calculating one-off metrics from information within the cluster - Operator + Creating or restoring from a data backup + Example: + + + Consider the following settings when creating a route: + + + + + An optional path, for path-based routes + + + + + A target port that the application listens to + + + + + An encryption strategy, depending on whether you need a secure or an insecure route + + + + 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. From d29aa2d971517ff540787c2dc237793aad78bec3 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Mon, 20 Nov 2023 18:13:43 +0000 Subject: [PATCH 3/6] Minor formatting --- en-US/Translation.xml | 3 --- 1 file changed, 3 deletions(-) diff --git a/en-US/Translation.xml b/en-US/Translation.xml index ff6f756..348e799 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -331,9 +331,6 @@ 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. From b92eef36b6cb84c5c54fec3d71a3adc62285ca64 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Mon, 20 Nov 2023 18:49:31 +0000 Subject: [PATCH 4/6] Content and formatting --- en-US/Punctuation.xml | 26 +++++++++++++------------- en-US/Translation.xml | 28 ++++++++++++++-------------- 2 files changed, 27 insertions(+), 27 deletions(-) diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index f2441cb..e076d80 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -636,18 +636,18 @@ PLAY [Gather and display facts for managed nodes] **************************** Punctuation in Tables - Use the following guidance for 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 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 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. + 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: @@ -747,17 +747,17 @@ PLAY [Gather and display facts for managed nodes] **************************** 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. When referring to a symbol in parentheses, the symbol name comes after any noun that describes the symbol. - Do not use the symbol on its own. + Do not use the symbol on its own. Referring to Punctuation Marks @@ -771,17 +771,17 @@ PLAY [Gather and display facts for managed nodes] ****************************Referring to Special Characters - To add a node, click the plus character (+). + 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. + Use the pipe character (|) to send the output of one program to the input of another program. - The hyphen after the greater-than sign (>) indicates that a newline character (\n) is not added to the end of the variable. + The hyphen after the greater-than sign (>) 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 348e799..7a69ed4 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -329,7 +329,7 @@ A complete sentence must include a subject and a verb. - It conveys a complete thought, and can stand on its own. + 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. @@ -338,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. @@ -358,7 +358,7 @@ - Deployments use replica sets, and deployment configurations use stateful sets. + Deployments use replica sets, and deployment configurations use stateful sets. @@ -369,12 +369,12 @@ Example: - Kubernetes networking provides the following capabilities: + Kubernetes networking provides the following capabilities: - Highly coupled container-to-container communications + Highly coupled container-to-container communications @@ -400,12 +400,12 @@ Example: - Common uses for jobs include the following tasks: + Common uses for jobs include the following tasks: - Initializing or migrating a database + Initializing or migrating a database @@ -423,12 +423,12 @@ Example: - Consider the following settings when creating a route: + Consider the following settings when creating a route: - An optional path, for path-based routes + An optional path, for path-based routes @@ -442,7 +442,7 @@ - + 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. @@ -451,18 +451,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 5eceac3ad08c6f3812be48b90274addd4da1b0f4 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Tue, 21 Nov 2023 16:11:40 +0000 Subject: [PATCH 5/6] Applied feedback --- en-US/Design.xml | 8 ++++---- en-US/Grammar.xml | 2 +- en-US/Punctuation.xml | 8 +++++--- en-US/Translation.xml | 3 ++- 4 files changed, 12 insertions(+), 9 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 6414394..6c29147 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -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 69e54a0..50fa863 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -217,7 +217,7 @@ - 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. + 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: diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index e076d80..8968c64 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -754,7 +754,9 @@ PLAY [Gather and display facts for managed nodes] **************************** For all other characters, use the character name followed by the symbol in parentheses. - When referring to a symbol in parentheses, the symbol name comes after any noun that describes the symbol. + For special character names that include a noun such as "sign", "symbol", or "character", provide the character name, the symbol in parentheses, and then the noun that describes the symbol, 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. @@ -771,13 +773,13 @@ PLAY [Gather and display facts for managed nodes] ****************************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 character ($). Use the pipe character (|) to send the output of one program to the input of another program. - The hyphen after the greater-than sign (>) indicates that a newline character (\n) is not added to the end of the variable. + The hyphen after the greater than symbol (>) indicates that a newline character (\n) is not added to the end of the variable. diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 7a69ed4..9d0220e 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -394,7 +394,8 @@ - Sometimes, list items might include some form of a verb, but without a subject and not capable of standing on their own. Such items count as sentence fragments, and are not ended with any punctuation. + 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: From 91e38c823d386a04e71720a317b69fd4c0bf5326 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Tue, 21 Nov 2023 16:36:26 +0000 Subject: [PATCH 6/6] Minor fixes --- en-US/Design.xml | 2 +- en-US/Punctuation.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 6c29147..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. diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 8968c64..2b29564 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -754,7 +754,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 symbol in parentheses, and then the noun that describes the symbol, 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.