Merge pull request #59535 from apinnick/ocg-yaml-ellipsis-guidelines

Update OCG YAML ellipsis guidelines and examples

Author: apinnick

contributing_to_docs/doc_guidelines.adoc

@@ -1209,15 +1209,15 @@ $ oc get endpoints --all-namespaces --template \
 # subscription-manager list
 ----
 
-* For snippets or sections of a file, use an ellipsis (`...`) to show that the file continues before and/or after the quoted block.
+* For snippets or sections of a file, use an ellipsis (`...` or `# ...` for YAML) to show that the file continues before or after the quoted block.
 +
 ----
 apiVersion: v1
 kind: Pod
 metadata:
   labels:
     test: liveness
-...
+# ...
 ----
 +
 or
@@ -1298,10 +1298,10 @@ apiVersion: config.openshift.io/v1
 kind: Scheduler
 metadata:
   name: cluster
-...
+# ...
 spec:
   defaultNodeSelector: node-role.kubernetes.io/app=
-...
+# ...
 ----
 
 .Example deeply nested key with full context for `.ports` array
@@ -1322,7 +1322,7 @@ spec:
 ----
 
 ==== Formatting
-Use the following conventions govern the layout of YAML for API objects.
+The following conventions govern the layout of YAML for API objects:
 
 - Begin YAML at the beginning of the left margin.
 - Use two-space indentation.
@@ -1335,7 +1335,8 @@ fieldName: |-
   This is a string.
   And it can be on multiple lines.
 ----
-- When truncating YAML, always precede an ellipsis with a pound so that the YAML is valid.
+- When truncating YAML, comment out the ellipsis (`# ...`) because three dots (`...`) in YAML is actually a link:https://yaml.org/spec/1.2.2/#22-structures[document end marker].
+- Use three hyphens (`---`) to separate YAML definitions in a single YAML file.
 
 .Example with array indentation flush with parent field
 ----
@@ -1347,7 +1348,7 @@ metadata:
   - key1: val1
   - key2: val2
 spec:
-...
+# ...
 ----
 
 .Example with block string for annotation
@@ -1364,7 +1365,7 @@ metadata:
         }
       ]
 spec:
-...
+# ...
 ----
 
 === Inline code or commands