From 978567039872d02611f22e5189ca62fe03b92bdc Mon Sep 17 00:00:00 2001 From: daobrien Date: Tue, 19 Jul 2022 15:18:22 +1000 Subject: [PATCH 01/25] Fixes extraneous comma. --- en-US/Grammar.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 1a65572..88cc7be 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -252,7 +252,7 @@
Sentence Structure - A sentence is one, complete thought. A sentence expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does). + A sentence is one complete thought. A sentence expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does). Consider the following points when constructing sentences: From e5916bb45ffd44d12b546568d2d4f575c8831e7c Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 1 Sep 2022 15:25:48 +0100 Subject: [PATCH 02/25] Applied various fixes for 6.0 --- en-US/Book_Design.xml | 4 +-- en-US/Design.xml | 10 +++--- en-US/Grammar.xml | 11 +++++-- en-US/Language.xml | 71 +++++++++++++++++++++++++++++++++++++++---- en-US/Punctuation.xml | 2 +- en-US/Translation.xml | 5 +-- 6 files changed, 85 insertions(+), 18 deletions(-) diff --git a/en-US/Book_Design.xml b/en-US/Book_Design.xml index b49b797..636518f 100644 --- a/en-US/Book_Design.xml +++ b/en-US/Book_Design.xml @@ -109,7 +109,7 @@
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 $productname" 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 (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.
@@ -135,7 +135,7 @@ About - Do not use "about" or "about $topic" as a title. The same reasoning applies here as to "overview". + Do not use "about" or "about <topic>" as a title. The same reasoning applies here as to "overview". diff --git a/en-US/Design.xml b/en-US/Design.xml index ab20c74..2ae6d07 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -863,10 +863,12 @@ $ vi myFile.txt Do not hyphenate or break a product name across lines, as in the following incorrect example: - - Open - -Shift - + + For advanced management capabilities with Red + Hat Satellite and cloud management services, use the Red + Hat Enterprise Linux Smart Management Add + -On. + diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 88cc7be..5062dee 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -11,7 +11,7 @@
Active Voice - Use the active voice ("Type ... to start Linuxconf".) rather than passive ("Linuxconf can be started by typing ...") whenever possible. Active voice makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count. + Use the active voice ("Type ... to start Linuxconf") rather than passive ("Linuxconf can be started by typing ...") whenever possible. Active voice makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count. This does not mean that the passive voice is forbidden. There are situations when using the passive voice is appropriate, such as release notes, technical notes, and similar material. @@ -471,10 +471,15 @@ - The individual member of the social community often receives information via visual, symbolic channels. - People read. (Translation by Richard Feynman.) + The fsck utility performs a file system verification on the XFS file system residing on the /dev/vdb1 partition. + The fsck utility verifies the XFS file system on the /dev/vdb1 partition. + + It is possible that the scheduled snapshot takes some time to be created. + Creating the scheduled snapshot might take time. + + Perform the installation of the product. Install the product. diff --git a/en-US/Language.xml b/en-US/Language.xml index e75460f..4b4add7 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -90,7 +90,16 @@ + + apples to apples + + + Do not use. Explain instead what is meant, such as "a fair comparison". + + + + ask (as a noun), make the ask @@ -102,6 +111,16 @@ + + + at the end of the day + + + Do not use. Explain what you mean, such as "considering all factors", or omit. + + + + at this point in time @@ -142,6 +161,16 @@ + + + boil the ocean + + + Do not use. State exactly what you mean, such as "increase the scope hugely". + + + + bottom line @@ -196,30 +225,30 @@ - eat your own dogfood + data point - 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. + Do not use. - data point + dig deeper, delve deeper - Do not use. + "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]." - dig deeper, delve deeper + drop the ball - "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]." + State instead exactly what you mean, such as "make a mistake". @@ -234,6 +263,16 @@ + + + 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. + + + + enterprise-ready @@ -265,6 +304,16 @@ + + + flog a dead horse + + + Do not use. Explain exactly what you mean, such as "a waste of effort". + + + + flying by the seat of your pants @@ -513,6 +562,16 @@ + + + on the same page + + + Instead of "ensure that everyone is on the same page", use wording such as "ensure that everyone is aligned" or "ensure that everyone is in agreement". + + + + over the wire diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 67c3a96..778d879 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -533,7 +533,7 @@ Deleted paragraph now that DocBook tagging no longer applies. --> Referring to Punctuation Marks - Use a semicolon to separate two parts of a sentence that can each stand on their own. + Use a semicolon to separate two parts of a sentence that can each stand on its own. The path contains the library qualifier in braces. diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 7800861..ad13330 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -78,8 +78,9 @@ It is important to provide sufficient 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. - If you use DocBook to build itemized, ordered, or variable (definition) lists, you can use the or attributes to specify the spacing between list items. - DocBook uses the spacing attribute by default. + If you use DocBook or AsciiDoc to build itemized or ordered lists, you can choose between normal spacing or the attribute to specify the spacing between list items. + In AsciiDoc, compact spacing is not supported for variable (definition) lists. + DocBook and AsciiDoc use the spacing attribute by default. From ae16f44fd55de6ada390fc86de467acd903d5e77 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 13 Oct 2022 17:51:52 +0100 Subject: [PATCH 03/25] Applied fixes from comments --- en-US/Design.xml | 33 +++++++++++++++++++-------------- en-US/Grammar.xml | 8 ++++---- en-US/Language.xml | 6 +++--- en-US/Translation.xml | 8 ++++---- 4 files changed, 30 insertions(+), 25 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 2ae6d07..b0c4b18 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -828,26 +828,26 @@ $ vi myFile.txt - - + Restrictions apply to abbreviating Red Hat product or solution names in public-facing documents. Always use the full name on first use. For some products, for example Red Hat OpenShift Container Platform, you can omit "Red Hat" after the first use. - - + Further restrictions apply to using acronyms and initialisms. In this same example, and only in technical documentation, "RHOCP" is acceptable after the first use of the full product name. - - + Do not include "Inc." when referring to Red Hat except in legal documents. - - + Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was ...". @@ -858,19 +858,24 @@ $ vi myFile.txt - - + - Do not hyphenate or break a product name across lines, as in the following incorrect example: + Do not hyphenate or break a product name across lines. + + Incorrect Example of Line Breaking + For advanced management capabilities with Red Hat Satellite and cloud management services, use the Red Hat Enterprise Linux Smart Management Add -On. - - - + + + +
diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 5062dee..e63167e 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -471,13 +471,13 @@ - The fsck utility performs a file system verification on the XFS file system residing on the /dev/vdb1 partition. - The fsck utility verifies the XFS file system on the /dev/vdb1 partition. + The fsck /dev/vdb1 command performs a file system verification on the XFS file system residing on the /dev/vdb1 partition. + The fsck /dev/vdb1 command verifies the XFS file system on the /dev/vdb1 partition. - It is possible that the scheduled snapshot takes some time to be created. - Creating the scheduled snapshot might take time. + Red Hat Insights provides different services for the administration and monitoring of the registered systems that can be used for troubleshooting and even remediation of the issues identified. + Red Hat Insights services administer and monitor registered systems to troubleshoot and remediate issues. diff --git a/en-US/Language.xml b/en-US/Language.xml index 4b4add7..2849fe0 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -162,7 +162,7 @@ - + bottom line @@ -316,7 +316,7 @@ - flying by the seat of your pants + fly by the seat of your pants Generally understood to mean "reacting to events as they occur". Difficult to offer alternatives without context. diff --git a/en-US/Translation.xml b/en-US/Translation.xml index ad13330..ff64063 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -78,13 +78,13 @@ It is important to provide sufficient 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. - If you use DocBook or AsciiDoc to build itemized or ordered lists, you can choose between normal spacing or the attribute to specify the spacing between list items. + + DocBook and AsciiDoc use the spacing attribute by default. --> - Use a list with normal spacing if any list item contains the following components: + In some authoring environments, you can choose between normal or compact spacing for lists. + Use a list with normal spacing if any list item contains the following components: From c2f2c1e2867d974e858bdfa60050f20b4de9411a Mon Sep 17 00:00:00 2001 From: daobrien Date: Fri, 14 Oct 2022 23:07:06 +1000 Subject: [PATCH 04/25] Fixes #409 and other required repairs. * Updated copyright year * Updated versions on links to style guides * Removed statement about providing DocBook guidance --- index.html | 26 ++++++-------------------- 1 file changed, 6 insertions(+), 20 deletions(-) diff --git a/index.html b/index.html index 4793b12..ead6135 100644 --- a/index.html +++ b/index.html @@ -2,7 +2,7 @@ - Stylepedia.net + Red Hat Style Guide @@ -43,30 +43,16 @@

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

-

- A dedicated guide to Docbook XML as used in Red Hat Training courses. -

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

-

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

- - - -

- - RHT DocBook XML Guide v4.0 -

-

Red Hat Brand Standards @@ -77,7 +63,7 @@

-

Copyright ©2021 Red Hat

+

Copyright ©2022 Red Hat

Powered by HTML5

From 6c791f645d0d388aacc0a6d8ecd8814974d46ba7 Mon Sep 17 00:00:00 2001 From: daobrien Date: Fri, 14 Oct 2022 23:23:19 +1000 Subject: [PATCH 05/25] Fixes #416 --- en-US/Language.xml | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/en-US/Language.xml b/en-US/Language.xml index e75460f..1306c99 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -907,15 +907,10 @@

-
Inclusive Language - In a blog post, Red Hat senior vice president and chief technology officer, Chris Wright, affirms a commitment for Red Hat to identify and replace problematic language that is potentially divisive and does not foster inclusion: + Chris Wright, Red Hat Chief Technology Officer and Senior Vice President, Global Engineering, affirms in a blog post a commitment for Red Hat to identify and replace problematic language that is potentially divisive and does not foster inclusion: @@ -1300,7 +1295,7 @@ Numbers (move from N entry) --> For times of day, use uppercase without periods, such as "11 AM". Use a nonbreaking space between the numeral and "AM" or "PM". - + Use "noon" or "12 noon" instead of "12 PM". From eb051e5b7d83440bfdee3b1443fdd9495f7e5dee Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 14 Oct 2022 16:25:28 +0100 Subject: [PATCH 06/25] Latest fixes --- en-US/Grammar.xml | 4 ++-- en-US/Translation.xml | 4 ---- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index e63167e..6d8bda5 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -471,8 +471,8 @@ - The fsck /dev/vdb1 command performs a file system verification on the XFS file system residing on the /dev/vdb1 partition. - The fsck /dev/vdb1 command verifies the XFS file system 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/Translation.xml b/en-US/Translation.xml index ff64063..952abc9 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -71,16 +71,12 @@ 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. 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. - In some authoring environments, you can choose between normal or compact spacing for lists. From 1ee5d515b470fceaf968e74da9ee25fa4ebc2c3e Mon Sep 17 00:00:00 2001 From: daobrien Date: Sat, 15 Oct 2022 10:45:58 +1000 Subject: [PATCH 07/25] Reapply update after merge conflict. --- index.html | 7 ------- 1 file changed, 7 deletions(-) diff --git a/index.html b/index.html index 9088f27..ead6135 100644 --- a/index.html +++ b/index.html @@ -53,13 +53,6 @@

Red Hat Technical Writing Style Guide v5.1

- - -

- - RHT DocBook XML Guide v4.0 -

-

Red Hat Brand Standards From be533cf7f9070e97c9d9df84fd56cbbaad665b69 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Mon, 24 Oct 2022 18:16:12 +0100 Subject: [PATCH 08/25] Applied third batch of enhancements for 6.0 (#420) * First batch of updates * Remaining enhancements --- en-US/Design.xml | 12 ++++++++++++ en-US/Grammar.xml | 12 ++++++++++++ en-US/Language.xml | 41 +++++++++++++++++++++++++++++++++++++++++ en-US/Punctuation.xml | 13 +++++++++++++ en-US/W.xml | 25 +++++++++++++++++++++++++ 5 files changed, 103 insertions(+) diff --git a/en-US/Design.xml b/en-US/Design.xml index b0c4b18..42da7ba 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -896,6 +896,12 @@ $ vi myFile.txt + + + Between a numeral and a unit of measurement. + + + @@ -914,6 +920,12 @@ $ vi myFile.txt + + + The crashkernel=auto setting requires at least 1{nbsp}GB of memory. + + + diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 6d8bda5..03fa1b6 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -268,6 +268,18 @@ The Start button, which you can find in the bottom left corner of your screen (also activated by the "Windows key" on your keyboard, the one between the Ctrl and Alt keys), provides a central starting point for applications and tasks, and can be customized according to your individual preferences so that it presents menu items relevant to you instead of presenting the standard items that come with the default installation of the operating system, items which, in my opinion, are irrelevant for most users these days who really only need access to an internet browser such as Google Chrome or Mozilla Firefox. + + + Preposition at the End of a Sentence + + Allow a preposition at the end of a sentence to avoid otherwise awkward wording. + + + + + For example, instead of "Click the workspace to which you want to switch", which can sound stilted, it flows better to use "Click the workspace to switch to". + + Run-on Sentences diff --git a/en-US/Language.xml b/en-US/Language.xml index 812a678..1141824 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1248,6 +1248,47 @@ + + + Use of "There Is" and "There Are" + + + Avoid "there is", "there are", and "there might be", because the subject of the sentence is unclear. + + + + + + + + + + Example + Improvement + + + + + + + The initial error message suggests there is a failure when opening a file. + The initial error message suggests a failure when opening a file. + + + + There are multiple static inventory formats supported by Ansible. + Ansible supports multiple static inventory formats. + + + + + + + +
+ + + Use of "Using" diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 778d879..9cc2dd2 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -422,6 +422,19 @@ If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. If not, the period goes outside. +

+
+ Slashes + + Avoid use of a slash character to mean either of two options. + + + For example, instead of "enable/disable", use "enable or disable". + + + Instead of "A and/or B", use "A or B", or "A, or B, or both". + +
Quotation Marks diff --git a/en-US/W.xml b/en-US/W.xml index 136935a..7543d1b 100644 --- a/en-US/W.xml +++ b/en-US/W.xml @@ -92,6 +92,31 @@ + + + whether + + + 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". + + + + + + + + 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". + + + + + + whitelist From 229892210ab72e08d2d81af9b36acf6cfc8afa33 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Tue, 25 Oct 2022 17:51:36 +0100 Subject: [PATCH 09/25] Applied second batch of enhancements for 6.0 (#419) * First changes for Enhancements 2 * Adding next batch of enhancements * Added further enhancements * Implemented fixes from review --- en-US/Design.xml | 74 ++++++++++++++++++++++- en-US/Grammar.xml | 2 +- en-US/L.xml | 11 ++++ en-US/Language.xml | 85 +++++++++++++++++++++++++-- en-US/O.xml | 6 ++ en-US/Punctuation.xml | 37 +++++++++++- en-US/Translation.xml | 133 +++++++++++++++++++++++++++++++++++++++++- 7 files changed, 338 insertions(+), 10 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 42da7ba..70da4db 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 is 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/Grammar.xml b/en-US/Grammar.xml index 03fa1b6..c3b1d36 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -590,7 +590,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/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/Language.xml b/en-US/Language.xml index 1141824..2c10804 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1063,12 +1063,26 @@ 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. + + @@ -1108,7 +1122,14 @@ 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. + + @@ -1151,7 +1172,14 @@ 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). + + @@ -1200,6 +1228,55 @@ + + 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 9cc2dd2..1ec0e8c 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. + + + + + + + +
+
Slashes @@ -446,7 +477,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. diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 952abc9..efbcffd 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -109,7 +109,6 @@ - The following discussion provides some initial insight into using lists correctly. See the IBM Style Guide for a full discussion. @@ -177,13 +176,108 @@ + + + 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: + + + ... + + + + + + + + + + + + + +
+
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. @@ -210,6 +304,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 a9b69e19b50daddc8cb945f6840563e5b9d601eb Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Tue, 25 Oct 2022 18:56:13 +0100 Subject: [PATCH 10/25] Applied first batch of enhancements for 6.0 (#414) * Adding snippet guidance Part 1 * Further enhancements to 6.0 * Fixes to implement feedback * Further fixes * Update to implement Fernando's feedback * Adding addressing of issue 399 to the scope * Implemented review comments --- en-US/Book_Info.xml | 2 +- en-US/Grammar.xml | 322 +++++++++++++++++++++++++++++++++++++++++- en-US/Language.xml | 91 ++++++++++++ en-US/Translation.xml | 67 +++++++++ 4 files changed, 476 insertions(+), 6 deletions(-) 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.01 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. From f85ad535ed99c86a6916f4a2ac662c87db97752f Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Tue, 1 Nov 2022 15:27:43 +0000 Subject: [PATCH 11/25] Added audience, new in this release, fix for 'like' entry (#422) * Added audience, new in this release, fix for 'like' entry * Minor fixes --- en-US/Audience.xml | 16 ++++++++ en-US/L.xml | 2 +- en-US/New.xml | 99 ++++++++++++++++++++++++++++++++++++++++++++++ en-US/Preface.xml | 3 ++ 4 files changed, 119 insertions(+), 1 deletion(-) create mode 100644 en-US/Audience.xml diff --git a/en-US/Audience.xml b/en-US/Audience.xml new file mode 100644 index 0000000..165da34 --- /dev/null +++ b/en-US/Audience.xml @@ -0,0 +1,16 @@ + + +%BOOK_ENTITIES; +]> +
+ 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. + + + 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. + + +
+ diff --git a/en-US/L.xml b/en-US/L.xml index 996b2d7..07c969b 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -105,7 +105,7 @@ - lifecycle + like Avoid "like" to mean "such as". diff --git a/en-US/New.xml b/en-US/New.xml index 9a1a58e..b9c953f 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -5,6 +5,105 @@ ]>
New in This Release + + Release 6.0 + Major update in October 2022 to add further style and grammar guidance: + + + + Added audience information for this guide. + + + Avoid redundant words. + + + Avoid a causative verb. + + + Words to use with countable nouns. + + + Use of "either-or" construction. + + + Avoid stating that something is easy to do or to use. + + + Avoid first person. + + + Use "following" with a noun. + + + Avoid hyphenating with an "-ly" prefix: added an example. + + + If-Then statements. + + + Make a full lead-in sentence to introduce a list. + + + Making list items parallel. + + + Updated guidance about use of compact lists. + + + Using noun strings. + + + Avoid a noun followed by an "-ing" word. + + + Using object names. + + + Placement of "only". + + + Preposition at the end of a sentence. + + + Use straight rather than curly quotation marks. + + + Avoid "(s)" for plural. + + + Added further examples of slang, idioms, and metaphors to avoid. + + + Avoid a slash. + + + Spacing with a unit of measurement. + + + Improved succinctness examples. + + + Avoid "there is", "there are". + + + Use "this", "that", "these", "those" with a noun. + + + Replaced use of "$" as a variable marker in this guide to use angle brackets instead. + + + Use of "whether" versus "if". + + + New or updated usage entries: like, once, while. + + + Various other fixes. + + + + + Release 5.1 Minor update in January 2022 to address some reported issues: diff --git a/en-US/Preface.xml b/en-US/Preface.xml index 37932d5..ebd2ae4 100644 --- a/en-US/Preface.xml +++ b/en-US/Preface.xml @@ -5,6 +5,9 @@ ]> Preface + + + From 60d35a3f1e1ca2e849a636513185b32e15716bde Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Wed, 2 Nov 2022 11:26:09 +0000 Subject: [PATCH 12/25] Revert addition of audience section --- en-US/Preface.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en-US/Preface.xml b/en-US/Preface.xml index ebd2ae4..d885b98 100644 --- a/en-US/Preface.xml +++ b/en-US/Preface.xml @@ -5,9 +5,9 @@ ]> Preface - + From 9955b8a1a964223beeb8fd95c1d5eb0964168afb Mon Sep 17 00:00:00 2001 From: daobrien Date: Fri, 4 Nov 2022 13:39:21 +1000 Subject: [PATCH 13/25] Addresses #424 Add info on using captions. A small subsection on when and when not to use captions and callouts. --- en-US/Design.xml | 111 ++++++++++++++++++++++++++++++----------------- 1 file changed, 71 insertions(+), 40 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 70da4db..14f45c1 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -21,7 +21,7 @@ Use title case also when referring to the titles of other publications, even if the title on the publication itself uses different casing. - + The currently accepted reference for determining title case is at https://titlecase.com/titlecase. @@ -46,7 +46,7 @@ Do not use terminating periods. - + Restrictions apply to abbreviating Red Hat product or solution names in public-facing documents. Always use the full name on first use. For some products, for example Red Hat OpenShift Container Platform, you can omit "Red Hat" after the first use. - + Further restrictions apply to using acronyms and initialisms. In this same example, and only in technical documentation, "RHOCP" is acceptable after the first use of the full product name. - + Do not include "Inc." when referring to Red Hat except in legal documents. - + Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was ...". @@ -928,24 +959,24 @@ $ vi myFile.txt - + Do not hyphenate or break a product name across lines. Incorrect Example of Line Breaking - + - For advanced management capabilities with Red - Hat Satellite and cloud management services, use the Red - Hat Enterprise Linux Smart Management Add + For advanced management capabilities with Red + Hat Satellite and cloud management services, use the Red + Hat Enterprise Linux Smart Management Add -On. - - + + - +
@@ -1002,7 +1033,7 @@ $ vi myFile.txt If you are working with images or other objects where space is especially tight, this rule is more flexible, but "Red Hat" should never be broken over two lines. - + Non-breaking spaces are not needed elsewhere in a product name and might cause undesirable line-breaking behavior. In particular, do not use non-breaking spaces between extended components of Red Hat product names. For example, "Red Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between any of the words after "Red Hat". From c2fcf7a2e620503d7858232bcf3bd5b24f30a99f Mon Sep 17 00:00:00 2001 From: daobrien Date: Fri, 4 Nov 2022 21:15:53 +1000 Subject: [PATCH 14/25] Fixed a grammerior. --- 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 14f45c1..ccc1f78 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -149,7 +149,7 @@ Refer to the Figures section in the IBM Style Guide for general advice about using figures, illustrations, and screen captures. - The following specific conventions apply to using captions and callouts with figures in Red Hat technical documentation, and is generally recommended. + The following specific conventions apply to using captions and callouts with figures in Red Hat technical documentation, and are generally recommended. From d123703b30544d29ea76b69689289f910acaaf38 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Mon, 7 Nov 2022 15:28:24 +0000 Subject: [PATCH 15/25] Added captions and callouts item to what's new (#428) --- en-US/New.xml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/en-US/New.xml b/en-US/New.xml index b9c953f..224c19b 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -13,6 +13,9 @@ Added audience information for this guide. + + Updated guidance about use of captions or callouts in figures. + Avoid redundant words. From d42d7f8c43fde6eb3bcaaa75d48dda3040210433 Mon Sep 17 00:00:00 2001 From: daobrien Date: Wed, 9 Nov 2022 10:34:42 +1000 Subject: [PATCH 16/25] Fixes #356. Removes big RH logo from centre of page. --- en-US/Book_Info.xml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index 2d513ce..32197bc 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -17,12 +17,6 @@ - - - - - - From 764cddcdb035eabbe3ccac98d69d31e0e44b1193 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Mon, 28 Nov 2022 17:52:09 +0000 Subject: [PATCH 17/25] Minor fix --- en-US/S.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/S.xml b/en-US/S.xml index c2b66bf..6f0433a 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -534,7 +534,7 @@ a programming and technical sense, it also means "Run the source - More generally, avoid use of "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL". When discussing Microsoft SQL Server, write "Microsoft SQL Server". When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL". + More generally, avoid the use of "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL". When discussing Microsoft SQL Server, write "Microsoft SQL Server". When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL". From 012828ed6e5500f04772d03637af6b4c554544ab Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Mon, 28 Nov 2022 18:27:14 +0000 Subject: [PATCH 18/25] Added example for 'unset' --- en-US/U.xml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/en-US/U.xml b/en-US/U.xml index 5e4f2a9..9e08ccd 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -77,6 +77,9 @@ This rule matches only TCP packets where the SYN flag is set and the ACK flag is cleared. + + Unset the ANSIBLE_NAVIGATOR_CONFIG environment variable so that the project's ./ansible-navigator.yml settings file is used for the remaining exercises. + From b3f8e2bec86c6dd6796dd8de1705521cce04fb78 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 30 Nov 2022 11:23:24 +0000 Subject: [PATCH 19/25] Added updated wording about verbs in titles (#444) --- en-US/Design.xml | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index ccc1f78..297d79f 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -46,14 +46,15 @@ Do not use terminating periods. - + File Names, Commands, and Related Terms From 2ad97924dc00caa5f2475db6f067a11a2e874030 Mon Sep 17 00:00:00 2001 From: Nicole Muller Date: Wed, 30 Nov 2022 09:50:51 -0700 Subject: [PATCH 20/25] update preface.xml to add in audience file and resolve issue #408 --- en-US/Preface.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en-US/Preface.xml b/en-US/Preface.xml index d885b98..703391e 100644 --- a/en-US/Preface.xml +++ b/en-US/Preface.xml @@ -5,9 +5,9 @@ ]> Preface - + From 63392354a15f11efa7da3530490926a261af4bb4 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Wed, 30 Nov 2022 17:02:31 +0000 Subject: [PATCH 21/25] Implement change from review --- en-US/U.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/U.xml b/en-US/U.xml index 9e08ccd..935a9f1 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -78,7 +78,7 @@ This rule matches only TCP packets where the SYN flag is set and the ACK flag is cleared. - Unset the ANSIBLE_NAVIGATOR_CONFIG environment variable so that the project's ./ansible-navigator.yml settings file is used for the remaining exercises. + Unset the ANSIBLE_NAVIGATOR_CONFIG environment variable so that the remaining exercises use the project's ./ansible-navigator.yml settings file. From cb94df16c87daaf7593e5587eebb46c33f58f70f Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Wed, 30 Nov 2022 17:04:04 +0000 Subject: [PATCH 22/25] Implement change from review --- en-US/S.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/S.xml b/en-US/S.xml index 6f0433a..46da1b8 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -534,7 +534,7 @@ a programming and technical sense, it also means "Run the source - More generally, avoid the use of "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL". When discussing Microsoft SQL Server, write "Microsoft SQL Server". When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL". + More generally, avoid "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL". When discussing Microsoft SQL Server, write "Microsoft SQL Server". When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL". From 917bd57c912d50462027f7342e2fd43928216bcc Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 30 Nov 2022 17:25:18 +0000 Subject: [PATCH 23/25] Final update to release notes for 6.0 (#446) * Final update to release notes for 6.0 * Updated publication month --- en-US/New.xml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/en-US/New.xml b/en-US/New.xml index 224c19b..64b0e98 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -7,14 +7,17 @@ New in This Release Release 6.0 - Major update in October 2022 to add further style and grammar guidance: + Major update in November 2022 to add further style and grammar guidance: Added audience information for this guide. - Updated guidance about use of captions or callouts in figures. + Updated guidance about the use of verbs in titles. + + + Updated guidance about the use of captions or callouts in figures. Avoid redundant words. @@ -98,7 +101,7 @@ Use of "whether" versus "if". - New or updated usage entries: like, once, while. + New or updated usage entries: like, once, unset, while. Various other fixes. From 794e842b14c52b3feaf4bd3d723696726ca0be9d Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 12 Dec 2022 13:37:15 +1000 Subject: [PATCH 24/25] Minor text tweaks. --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index ead6135..c03c6a3 100644 --- a/index.html +++ b/index.html @@ -41,7 +41,7 @@

- The official style guide for Red Hat technical documentation, including how to write for translation, common mistakes to avoid, rules for everyday punctuation, and grammar. + 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.

From aaf0b32af99e603c1a27e01da8fa9f8f4ae422a3 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Mon, 12 Dec 2022 10:24:30 +0000 Subject: [PATCH 25/25] Apply fixes from Nicole and update release month (#449) --- en-US/Language.xml | 8 ++++---- en-US/New.xml | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/en-US/Language.xml b/en-US/Language.xml index 92b3568..e9d6273 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1212,13 +1212,13 @@ - To create another administrator, click New on the File menu. + To create another administrator, click File > New. - To create another administrator account, click New on the File menu. + To create another administrator account, click File > New. - Or: To set privileges for another administrator, click New on the File menu. + Or: To set privileges for another administrator, click File > New. @@ -1268,7 +1268,7 @@ 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). + Or: Use the utility to run activities, and then save your settings (if the process consists of two separate steps, of which the utility does only one). diff --git a/en-US/New.xml b/en-US/New.xml index 64b0e98..d35bcff 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -7,7 +7,7 @@ New in This Release Release 6.0 - Major update in November 2022 to add further style and grammar guidance: + Major update in December 2022 to add further style and grammar guidance: