Updates on referring to object names and using realistic usernames (#554)

* Updates on referring to object names and using realistic usernames

* Apply review comments

Author: julian-cable

en-US/Design.xml

@@ -16,7 +16,7 @@
 				<title>Capitalization</title>
 					<para>
 					The standard for all Red&nbsp;Hat technical documentation is title case for all headings and titles.
-            Table titles and procedure headings fall into this category; standard title case capitalization rules apply.
+            Table titles and procedure titles fall into this category; standard title case capitalization rules apply.
 					</para>
 		</formalpara>
 			<para>
@@ -724,8 +724,8 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest
 
 				</formalpara>
 				 <para>
-					For example, you are the system administrator at Global Banking and you are asked to set up permissions to the accounting directory for the following users: Huong Sabo, Jerlene Paluch, Abby Quincy, Fricis Ritcher, and Jaya Lamont. 
-					Huong is a department manager and needs read access to the accounting directory. Jerlene is the lead accountant and needs both read and write access.
+					For example, you are the system administrator at Global Banking and you are asked to set up permissions to the accounting directory for the following users: Huong Sabo, Jolene Paluch, Abby Quincy, Francis Ritcher, and Jaya Lamont. 
+					Huong is a department manager and needs read access to the accounting directory. Jolene is the lead accountant and needs both read and write access.
 				</para>
 				 <formalpara id="choosing-realistic-names">
 					<title>Choosing a Realistic Name</title>
@@ -743,17 +743,28 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest
 							In examples or scenarios, you can use a person's name and then use a gender-specific pronoun to refer to that name. Vary the use of proper names in documentation. Use names that represent various ethnic backgrounds, genders, and locations.
 						</para>
 
+					</listitem>
+					 <listitem>
+						<para>
+							Include a diverse set of names in your examples to reflect the diversity of the real world.
+              For example, use gender-inclusive and culturally diverse names that suggest various backgrounds in examples to avoid implying that only certain groups have specific skills.
+						</para>
+
 					</listitem>
 					 <listitem>
 						<para>
 							Do not use copyrighted fictional characters in examples, and do not use real people.
 						</para>
 
 					</listitem>
+
 					 <listitem>
 						<para>
-							Include a diverse set of names in your examples to reflect the diversity of the real world.
-              For example, use male, female, and culturally diverse names that suggest various backgrounds in examples to avoid implying that only certain groups have specific skills.
+							When choosing names, also consider how those names might appear in email addresses, usernames, and similar contexts.
+							Avoid name combinations or abbreviations that result in unintended meanings, such as slang.
+							An example that works well might be "John Smith", with an email address of <email>jsmith@example.com</email>.
+							However, for the name "Brian Strong", a corresponding email address of <email>bstrong@example.com</email> might not work so well (when read out, it sounds like "be strong").
+							Consider also any implications for names in different languages. 
 						</para>
 
 					</listitem>
@@ -872,7 +883,7 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest
 
 		</table>
 			 <para>
-				Place an object name before the noun that it modifies rather than after the noun.
+				In most cases, place an object name before the noun that it modifies rather than after the noun.
 			</para>
 
 			 <table>
@@ -899,6 +910,41 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest
 
 			</tgroup>
 
+		</table>
+			 <para>
+				However, in some cases, the sentence might be easier to understand if the noun appears first, or if additional language separates the object name from the noun. 
+				For example, if the noun refers to a password, a value, or a status, then consider stating the noun first, or including explanatory language between the object name and the noun, or doing both.
+			</para>
+
+			 <table>
+			<title></title>
+			 <tgroup cols="2" colsep="1" rowsep="1">
+				<colspec colname="c1"></colspec>
+				 <colspec colname="c2"></colspec>
+				 <thead>
+					<row>
+						<entry> Example </entry>
+						 <entry> Improvement </entry>
+
+					</row>
+
+				</thead>
+				 <tbody>
+					<row>
+						<entry> Log in as the <systemitem>admin</systemitem> user with the <systemitem>redhat</systemitem> password. </entry>
+						 <entry> Log in as the <systemitem>admin</systemitem> user with <systemitem>redhat</systemitem> as the password. </entry>
+
+					</row>
+					<row>
+						<entry> Define the <varname>backup_tmp</varname> variable with the <varname>/tmp</varname> value in the <filename>defaults/main.yml</filename> file. </entry>
+						 <entry> Define the <varname>backup_tmp</varname> variable with a value of <varname>/tmp</varname> in the <filename>defaults/main.yml</filename> file. </entry>
+
+					</row>
+
+				</tbody>
+
+			</tgroup>
+
 		</table>
 
 		</section>