From e5916bb45ffd44d12b546568d2d4f575c8831e7c Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 1 Sep 2022 15:25:48 +0100 Subject: [PATCH 1/3] 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 2/3] 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 eb051e5b7d83440bfdee3b1443fdd9495f7e5dee Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 14 Oct 2022 16:25:28 +0100 Subject: [PATCH 3/3] 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.