Merge pull request #407 from StyleGuides/jcable/6.0-fixes

daobrien · web-flow · commit 20484982701f · 2022-10-18T11:00:37.000+10:00
Applied various fixes for 6.0
diff --git a/en-US/Book_Design.xml b/en-US/Book_Design.xml
@@ -109,7 +109,7 @@
 	 <section id="introductions">
 		<title>Introductions</title>
 		 <para>
-			The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory (TM) tools, that Red&nbsp;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&nbsp;Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to &lt;product_name&gt;" 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.
 		</para>
 
 	</section>
@@ -135,7 +135,7 @@
 		 <formalpara id="about">
 			<title>About</title>
 			 <para>
-				Do not use "about" or "about $topic" as a title. The same reasoning applies here as to "overview".
+				Do not use "about" or "about &lt;topic&gt;" as a title. The same reasoning applies here as to "overview".
 			</para>
 
 		</formalpara>
diff --git a/en-US/Design.xml b/en-US/Design.xml
@@ -828,26 +828,26 @@ $ vi myFile.txt
 			</para>
 
 		</note>
-		 <itemizedlist>
-			<listitem>
+<!-- <itemizedlist> 
+		<listitem>		-->		 
 				<para>
 					Restrictions apply to abbreviating Red&nbsp;Hat product or solution names in public-facing documents. Always use the full name on first use. For some products, for example Red&nbsp;Hat OpenShift Container Platform, you can omit "Red&nbsp;Hat" after the first use.
 				</para>
 
-			</listitem>
-			 <listitem>
+<!-- 		<listitem> 
+			 </listitem>		-->	
 				<para>
 					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.
 				</para>
 
-			</listitem>
-			 <listitem>
+<!-- 		<listitem> 
+			 </listitem>		-->	
 				<para>
 					Do not include "Inc." when referring to Red&nbsp;Hat except in legal documents.
 				</para>
 
-			</listitem>
-			 <listitem>
+<!-- 		<listitem> 
+			 </listitem>		-->	
 				<para>
 					Do not use articles in front of product names. For example, do not write "the JBoss Enterprise&nbsp;Application&nbsp;Platform was ...".
 				</para>
@@ -858,17 +858,24 @@ $ vi myFile.txt
 
 				</note>
 
-			</listitem>
-			 <listitem>
+<!-- 		<listitem> 
+			 </listitem>		-->	
 				<para>
-					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.
 				</para>
-					<programlisting>
-					Open
-					-Shift
-					</programlisting>
-			</listitem>
-		</itemizedlist>
+				<example>
+				<title>Incorrect Example of Line Breaking</title>
+				<para> 
+				<literallayout>
+					For advanced management capabilities with Red   
+					Hat Satellite and cloud management services, use the Red     
+					Hat Enterprise Linux Smart Management Add    
+					-On.
+				</literallayout>	
+				</para>	
+				</example>
+<!-- 		<listitem> 
+			 </itemizedlist>		-->	
 
 	</section>
 	 <section id="nonbreaking-spaces">
diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml
@@ -11,7 +11,7 @@
 	 <section id="active-voice">
 		<title>Active Voice</title>
 		 <para>
-			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.
 		</para>
 		 <para>
 			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 @@
 				</thead>
 				 <tbody>
 					<row>
-						<entry> The individual member of the social community often receives information via visual, symbolic channels. </entry>
-						 <entry> People read. (Translation by Richard Feynman.) </entry>
+						<entry> The <command>fsck /dev/vdb1</command> command performs a file system check on the XFS file system residing on the <filename>/dev/vdb1</filename> partition. </entry>
+						 <entry> The <command>fsck /dev/vdb1</command> command checks the XFS file system on the <filename>/dev/vdb1</filename> partition. </entry>
 
 					</row>
+					<row>
+						<entry> Red&nbsp;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. </entry>
+						 <entry> Red&nbsp;Hat Insights services administer and monitor registered systems to troubleshoot and remediate issues. </entry>
+
+					</row>					
 					<row>
 						<entry> Perform the installation of the product. </entry>
 						 <entry> Install the product. </entry>
diff --git a/en-US/Language.xml b/en-US/Language.xml
@@ -90,7 +90,16 @@
 				</listitem>
 
 			</varlistentry>
+			 <varlistentry>
+				<term>apples to apples</term>
+				 <listitem>
+					<para>
+						Do not use. Explain instead what is meant, such as "a fair comparison". 
+					</para>
 
+				</listitem>
+
+			</varlistentry>
 			 <varlistentry>
 				<term>ask (as a noun), make the ask</term>
 				 <listitem>
@@ -102,6 +111,16 @@
 
 				</listitem>
 
+			</varlistentry>
+			 <varlistentry>
+				<term>at the end of the day</term>
+				 <listitem>
+					<para>
+						Do not use. Explain what you mean, such as "considering all factors", or omit.
+					</para>
+
+				</listitem>
+
 			</varlistentry>
 			 <varlistentry>
 				<term>at this point in time</term>
@@ -143,6 +162,16 @@
 				</listitem>
 
 			</varlistentry>
+<!-- 		 <varlistentry>
+				<term>boil the ocean</term>
+				 <listitem>
+					<para>
+						Do not use. State exactly what you mean, such as "increase the scope hugely".
+					</para>
+
+				</listitem>
+
+			</varlistentry>  -->
 			 <varlistentry>
 				<term>bottom line</term>
 				 <listitem>
@@ -196,30 +225,30 @@
 
 			</varlistentry>
 			 <varlistentry>
-				<term>eat your own dogfood</term>
+				<term>data point</term>
 				 <listitem>
 					<para>
-						Developer-speak. It means to use your own products. You can get a detailed description at <ulink url="http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food">http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food</ulink>.
+						Do not use.
 					</para>
 
 				</listitem>
 
 			</varlistentry>
 			 <varlistentry>
-				<term>data point</term>
+				<term>dig deeper, delve deeper</term>
 				 <listitem>
 					<para>
-						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]."
 					</para>
 
 				</listitem>
 
 			</varlistentry>
 			 <varlistentry>
-				<term>dig deeper, delve deeper</term>
+				<term>drop the ball</term>
 				 <listitem>
 					<para>
-						"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".
 					</para>
 
 				</listitem>
@@ -234,6 +263,16 @@
 
 				</listitem>
 
+			</varlistentry>
+			 <varlistentry>
+				<term>eat your own dogfood</term>
+				 <listitem>
+					<para>
+						Developer-speak. It means to use your own products. You can get a detailed description at <ulink url="http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food">http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food</ulink>.
+					</para>
+
+				</listitem>
+
 			</varlistentry>
 			 <varlistentry>
 				<term>enterprise-ready</term>
@@ -267,7 +306,17 @@
 
 			</varlistentry>
 			 <varlistentry>
-				<term>flying by the seat of your pants</term>
+				<term>flog a dead horse</term>
+				 <listitem>
+					<para>
+						Do not use. Explain exactly what you mean, such as "a waste of effort".
+					</para>
+
+				</listitem>
+
+			</varlistentry>
+			 <varlistentry>
+				<term>fly by the seat of your pants</term>
 				 <listitem>
 					<para>
 						Generally understood to mean "reacting to events as they occur". Difficult to offer alternatives without context.
@@ -513,6 +562,16 @@
 
 				</listitem>
 
+			</varlistentry>
+			 <varlistentry>
+				<term>on the same page</term>
+				 <listitem>
+					<para>
+						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".
+					</para>
+
+				</listitem>
+
 			</varlistentry>
 			 <varlistentry>
 				<term>over the wire</term>
diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml
@@ -533,7 +533,7 @@ Deleted paragraph now that DocBook tagging no longer applies. -->
 		<example><title>Referring to Punctuation Marks</title>
 
           <para>
-            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.
           </para>
 		  <para>
             The path contains the library qualifier in braces.
diff --git a/en-US/Translation.xml b/en-US/Translation.xml
@@ -71,19 +71,16 @@
     <para>
         You can nest lists, but try to keep the number of levels to two or fewer.
         To nest procedures in DocBook, use &lt;substep&gt; elements.
-<!-- In AsciiDoc? -->
     </para>
     <section><title>Formatting Lists for Readability</title>
       <para>
         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 <option>compact</option> or <option>normal</option> attributes to specify the spacing between list items.
-        DocBook uses the <option>normal</option> spacing attribute by default.
-		<!-- In AsciiDoc? -->
       </para>
       <para>
-        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:
       </para>
       <itemizedlist>
         <listitem>
