Merge pull request #79617 from aireilly/update-yaml-guidelines

Author: aireilly

contributing_to_docs/doc_guidelines.adoc

@@ -753,7 +753,32 @@ If you are upgrading a cluster in a restricted network, install the `oc` version
 
 Note that you must set and unset each temporary attribute that you introduce to an assembly. Use the temporary attributes in the applicable ifdef and ifndef statements to vary text between the assemblies. The preceeding example uses `restricted` as the temporary attribute to display an additional paragraph for the assembly with the `updating-restricted-network-cluster` context attribute.
 
-== Node names
+[id="do-not-use-sensitive-information-in-docs"]
+== Ensuring that you do not include sensitive information
+
+If you use sample code that you get from Engineering or QE team members, review the code for potentially sensitive data from customer or test environments.
+Do not include test or customer data in any field or comment in the YAML.
+
+Examples of sensitive information from customer or test environments can include:
+
+Node names::
+For example, internal company or customer server names.
+See <<node-names>> for more information.
+
+IP addresses::
+Replace all public IP addresses with generic IP addresses.
+See <<ip-addresses>> for more information.
+
+MAC addresses::
+Ensure that any MAC addresses that you include in source example are generic and do not identify real machines.
+See <<mac-addresses>> for more information.
+
+Sensitive Red Hat, customer, or partner information::
+Remove or rework text or comments that inadvertently describe sensitive Red Hat, customer, or partner data, or names new or un-released features or products.
+See <<sensitive-or-unreleased-information>> for more information.
+
+[id="node-names"]
+=== Node names
 
 Do not use internal company server names in commands or example output. Provide generic OpenShift Container Platform node name examples that are not provider-specific, unless required. Where possible, use the example.com domain name when providing fully qualified domain names (FQDNs).
 
@@ -813,7 +838,8 @@ control-plane-3.example.com   Ready    master   41m   v1.19.0+9f84db3
 Some provider-formatted hostnames include IPv4 addresses. An OpenShift Container Platform node name typically reflects the hostname of a node. If node names in your output need to be provider-specific and require this format, use private IPv4 addresses. For example, you could use `ip-10-0-48-9.example.com` as a node name that includes a private IPv4 address.
 ====
 
-== IP addresses
+[id="ip-addresses"]
+=== IP addresses
 
 You may include IPv4 addresses from test clusters in examples in the documentation, provided that they are private. Private IPv4 addresses fall into one of the following ranges:
 
@@ -832,6 +858,39 @@ Replace all public IP addresses with an address from the following blocks. These
 There might be advanced networking examples that require specific IP addresses, or cloud provider-specific examples that require a public IP address. Contact a subject matter expert if you need assistance with replacing IP addresses.
 ====
 
+[id="mac-addresses"]
+=== MAC addresses
+
+Ensure that any MAC addresses that you include in source example are generic and do not identify real hosts.
+
+[id="sensitive-or-unreleased-information"]
+=== Sensitive or customer-identifying data
+
+Ensure that you do not include text or comments that inadvertently describes sensitive Red Hat, customer, or partner data.
+
+Possible sources of customer-identifying data includes:
+
+* Unreleased product names or project code words
+* Customer and partner names
+* Code comments
+* Example YAML CR snippets
+* Sample application code
+* Logs
+* Configuration files
+* Command output
+* Network or architecture diagrams
+* Network packet captures
+* Package version numbers
+* Heap dumps
+
+Where possible, replace specific details with generic examples.
+
+[NOTE]
+====
+There might be advanced examples that require specific details, or multipart examples that require specific names to make sense.
+If you have any doubt about what you are documenting, contact a subject matter expert or team lead.
+====
+
 [id="links-conditionals-assemblies"]
 == Links, hyperlinks, and cross references
 Links can be used to cross-reference internal assemblies or send readers to external information resources for further reading.