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..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,17 +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. - - Open - -Shift - - - + + 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 88cc7be..6d8bda5 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 /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. + + 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. + + Perform the installation of the product. Install the product. diff --git a/en-US/Language.xml b/en-US/Language.xml index e75460f..2849fe0 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 @@ -143,6 +162,16 @@ + 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 @@ -267,7 +306,17 @@ - flying by the seat of your pants + flog a dead horse + + + Do not use. Explain exactly what you mean, such as "a waste of effort". + + + + + + + fly by the seat of your pants Generally understood to mean "reacting to events as they occur". Difficult to offer alternatives without context. @@ -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..952abc9 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -71,19 +71,16 @@ 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. - 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. - - 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: