From e55545e48ca2ec40b4becaf5b8f0d609e9026e78 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 6 Oct 2022 16:02:03 +0100 Subject: [PATCH 1/4] First changes for Enhancements 2 --- en-US/L.xml | 11 +++++++++++ en-US/Punctuation.xml | 6 +++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/en-US/L.xml b/en-US/L.xml index bbd920b..996b2d7 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -104,6 +104,17 @@ + + lifecycle + + + Avoid "like" to mean "such as". + For example, instead of "Namespaces can include resources like network interfaces", use "Namespaces can include resources such as network interfaces". + + + + + Linux diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 67c3a96..d34c588 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -433,7 +433,11 @@ Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quotation; if not, they go outside. --> - + + 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. + Refer to the "Typographical Considerations" section in the "Quotation Marks" topic in the IBM Style Guide. + In technical documentation, place punctuation marks, including periods, commas, question marks, exclamation points, dashes, and semicolons inside the quotation marks if they are part of the quotation or part of a programming element that uses quotation marks; if not, place punctuation marks outside the quotation marks. If a sentence ends with a quotation, use only one punctuation mark to end the sentence, and place it inside the closing quotation mark if it is part of the quotation, or outside if it is not. From 4de224125114f811dc70d628d128d14d68158871 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 7 Oct 2022 17:45:57 +0100 Subject: [PATCH 2/4] Adding next batch of enhancements --- en-US/Grammar.xml | 2 +- en-US/Translation.xml | 37 ++++++++++++++++++++++++++++++++++++- 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 88cc7be..8d8b791 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -573,7 +573,7 @@ Split contractions and abbreviations into separate paragraphs. --> Do not hyphenate "open source", even when used as a complex adjective. - Do not hyphenate a compound that includes an adverb ending in -ly, whether it comes before or after the noun. This is described in Chicago Manual of Style 7.82. + Do not hyphenate a compound that includes an adverb that ends in -ly, whether it comes before or after the noun, because it is never ambiguous. This is described in Chicago Manual of Style 7.82. For example, "Red Hat Enterprise Linux is a production-ready, commercially supported Linux distribution." diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 7800861..6c13ba4 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -186,7 +186,7 @@
Noun Stacking - Modifier strings (modifier + noun + noun sentence format) and over-modified nouns (or noun stacks) are especially difficult to translate, particularly when several different combinations might make sense. + Modifier strings (modifier + noun + noun sentence format) and over-modified nouns (or noun stacks) are especially difficult to translate, particularly when several different combinations might make sense. Avoid a stack of more than three consecutive nouns. @@ -213,6 +213,41 @@ For new users, set the parameters to the default printer configuration. Enter the maximum length of time, in number of days, that you want to keep the address lists updated by automatic synchronization. Then, press Enter. + + Standard system log management configuration rotates log files every week. + Standard configuration of system log management rotates log files every week. + + + + + + + +
+ + Avoid a noun followed by a word that ends in -ing. Such a construction is difficult to translate. + + + + + + + + + + Example + Improvement + + + + + + + The nmap utility scans privileged TCP ports looking for services. + The nmap utility scans privileged TCP ports to look for services. + + + From 6af6a1cb4828e5bf2f7426c20a5a2a77cdc69135 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Mon, 17 Oct 2022 18:40:47 +0100 Subject: [PATCH 3/4] Added further enhancements --- en-US/Design.xml | 74 ++++++++++++++++++++++++++++++++- en-US/Language.xml | 85 ++++++++++++++++++++++++++++++++++++-- en-US/O.xml | 6 +++ en-US/Punctuation.xml | 31 ++++++++++++++ en-US/Translation.xml | 96 ++++++++++++++++++++++++++++++++++++++++++- 5 files changed, 285 insertions(+), 7 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index ab20c74..c471833 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -702,7 +702,7 @@ $ vi myFile.txt
Referring to Object Names - Do not use object names as part of normative grammar. A sentence should be complete without the object name. + When using object names, write a sentence so that it would be complete without the object name.
@@ -721,7 +721,77 @@ $ vi myFile.txt Find the current default StorageClass. - Either: Find the current default storage class. Or: Find the current default StorageClass value. + + + Either: Find the current default storage class. + + + Or: Find the current default StorageClass value. + + + + + + + + + +
+ + Avoid starting or ending a sentence with an object name. + + + + + + + + + + Example + Improvement + + + + + + + Umount /mnt/save. + Unmount the /mnt/save directory. + + + + Modify the /etc/resolv.conf file to use this nameserver. + Modify the /etc/resolv.conf file to use this name server. + + + + + + + +
+ + Place an object name before the noun that it modifies rather than after the noun. + + + + + + + + + + Example + Improvement + + + + + + + Enable the default module stream for the module python36 and install all packages from that stream. + Enable the default module stream for the python36 module and install all packages from that stream. diff --git a/en-US/Language.xml b/en-US/Language.xml index e75460f..19debdd 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1009,12 +1009,26 @@ Numbers (move from N entry) --> 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. + + + 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. + + + It can be held in memory. + + + Or: It might be held in memory. + + @@ -1054,7 +1068,14 @@ Numbers (move from N entry) --> To create another administrator, click New on the File menu. - To create another administrator account, click New on the File menu. OR To set privileges for another administrator, click New on the File menu. + + + To create another administrator account, click New on the File menu. + + + Or: To set privileges for another administrator, click New on the File menu. + + @@ -1097,7 +1118,14 @@ Numbers (move from N entry) --> Use the utility to run activities and save your settings. - Depending on the meaning: Use the utility to run activities and to save your settings (if the utility does both functions). Or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). + Depending on the meaning: + + Use the utility to run activities and to save your settings (if the utility does both functions). + + + Or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). + + @@ -1146,6 +1174,55 @@ Numbers (move from N entry) --> + + Misplaced Only + + + Ensure that "only" is placed directly before the word that it modifies, which often should not be a verb. + +
+ + + + + + + Example + Improvement + + + + + + + + + Users can only delete files that they own. + + + (Misleadingly suggests that users cannot take any actions other than deletion on those files) + + + + + Users can delete only files that they own. + + + (Clarifies the files that deletion applies to) + + + + + + + + + +
+ + + + Pronouns diff --git a/en-US/O.xml b/en-US/O.xml index 6bffc0d..49ce877 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -94,6 +94,12 @@ 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". + + + Example 2: Instead of "Once you generate the SSH keys, you can find them by default in the .ssh/ directory", use "After you generate the SSH keys, you can find them by default in the .ssh/ directory". + diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index d34c588..a3fb448 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -422,6 +422,37 @@ 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. + + + + + + + + + + + Example + Improvement + + + + + + + Choose the item(s). + Choose the items. + + + + + + + +
+
Quotation Marks diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 6c13ba4..77627d5 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -112,7 +112,6 @@ - The following discussion provides some initial insight into using lists correctly. See the IBM Style Guide for a full discussion. @@ -180,6 +179,101 @@ + + + Make items in a list grammatically parallel. + + + In the following example, the original three list items inconsistently use an infinitive verb form, and then a gerund, and then an imperative. In the improved example, all three list items consistently use an imperative statement. + + + + + + + + + Example + Improvement + + + + + + + + + + + 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: + + + ... + + + + + + + + + + + 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 793ad1cfb7f864e7b9562adb54e2e79ac7886616 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Tue, 25 Oct 2022 12:16:50 +0100 Subject: [PATCH 4/4] Implemented fixes from review --- en-US/Design.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index f0d61a1..70da4db 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -702,7 +702,7 @@ $ vi myFile.txt
Referring to Object Names - When using object names, write a sentence so that it would be complete without the object name. + When using object names, write a sentence so that it is complete without the object name.