Merge pull request #190 from StyleGuides/style-guide-issue-173

Addresses Style Guide Issue #173
StyleGuides · Jul 10, 2020 · 1dceaa0 · 1dceaa0
2 parents 1048906 + 8eb2133
commit 1dceaa0
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 4 deletions.
diff --git a/en-US/Design.xml b/en-US/Design.xml
@@ -721,6 +721,38 @@ $ vi myFile.txt
 		</para>
 
 	</section>
+
+	<section id="making-recommendations">
+	 <title>Making Recommendations</title>
+		<para>
+		When making a recommendation, the preferred verbiage is "Red&nbsp;Hat recommends..." instead of the common but indirect "It is recommended...".
+		Recommendations can include best practices, recommended practices, and product-specific suggestions.
+		Refer to <xref linkend="avoiding-confusing-language"/> for information on using the terms "best practices" and "recommended practices" in Red&nbsp;Hat documentation.
+	  </para>
+		<example>
+			<title>
+				(incorrect)
+			</title>
+		<para>
+	    "Although the attack surface is reduced to the same-project traffic, it is recommended to create multiple service accounts within a project."
+	  </para>
+	  <para>
+		  "It is recommended to generate a service account for each microservice in your project."
+	  </para>
+	</example>
+	<example>
+		<title>
+			(correct)
+		</title>
+	  <para>
+		"Although the attack surface is reduced to the same-project traffic, Red&nbsp;Hat recommends creating multiple service accounts within a project."
+	  </para>
+	<para>
+  	"Red&nbsp;Hat recommends that you generate a service account for each microservice in your project."
+	</para>
+</example>
+ </section>
+
 	 <section id="citing-other-works">
 		<title>Citing Other Works</title>
 		 <formalpara id="other-books">
@@ -779,6 +811,7 @@ $ vi myFile.txt
 		</itemizedlist>
 
 	</section>
+
 	 <section id="other-authors">
 		<title>Citing Other Authors</title>
 		 <para>
@@ -794,4 +827,3 @@ $ vi myFile.txt
 	</section>
 
 </chapter>
-
diff --git a/en-US/Slang.xml b/en-US/Slang.xml
@@ -23,8 +23,10 @@
 					<para>
 						This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red&nbsp;Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices."
 					</para>
-
-				</listitem>
+					<para>
+						See the section <xref linkend="making-recommendations" /> for additional information about recommendations in Red&nbsp;Hat documentation.
+					</para>
+		 		 </listitem>
 
 			</varlistentry>
 			 <varlistentry id="first-come-first-served">
@@ -872,4 +874,3 @@
 	</section>
 
 </chapter>
-