adding local YAML contrib guidelines

Author: aireilly

contributing_to_docs/doc_guidelines.adoc

@@ -830,6 +830,69 @@ Embedding external files is restricted for files that change frequently, like te
 You must get approval from the Engineering, QE, and Docs teams before embedding an external file.
 ====
 
+== Embedding a local YAML file
+
+You can embed local YAML files in AsciiDoc modules.
+Consider embedding a local YAML file when you have a complete and valid YAML file that you want to use.
+This is useful when you want to include a complete YAML CR in the docs.
+The YAML file that you include must be a local file maintained in the link:https://github.com/openshift/openshift-docs[openshift-docs] GitHub repository.
+Use the `include` directive to target the local file.
+
+To use a local YAML file, add it to the `snippets/` folder, and include it in your module. For example:
+
+[source,yaml]
+----
+\include::snippets/install-config.yaml[]
+----
+
+[NOTE]
+====
+Do not include link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-lines/[lines by content ranges]. This approach can lead to content errors when the included file is subsequently updated.
+====
+
+[IMPORTANT]
+====
+If the YAML file you want to include is from a GitHub repository that is managed by the `openshift` GitHub user, link to the file directly rather than copying the file to the `/openshift-docs` folder.
+====
+
+[discrete]
+=== Using AsciiDoc callouts in the YAML
+
+You can use AsciiDoc callouts in the YAML file.
+Comment out the callout in the YAML file to ensure that file can still be parsed as valid YAML.
+Asciidoctor recognises the commented callout and renders it correctly in the output.
+For example:
+
+[source,yaml]
+----
+apiVersion: v1 # <1>
+----
+
+[discrete]
+=== Version and upgrade implications
+
+Carefully consider the version and upgrade implications of including the local YAML file in your content. Including a local YAML file can increase the maintenance overhead for the content.
+If you have a doubt, talk to your content strategist or docs team lead.
+
+[discrete]
+=== Validating the local YAML file
+
+Before you include the YAML file, use a YAML linter or the `oc` CLI to verify that the YAML is valid.
+For example, to validate the `snippets/SiteConfig.yaml` file using `oc`, log in to a cluster and run the following command from a terminal opened in the `openshift-docs/` folder:
+
+[source,terminal]
+----
+$ oc apply -f snippets/SiteConfig.yaml --dry-run=client
+----
+
+.Example output
+[source,terminal]
+----
+siteconfig.ran.openshift.io/example-sno created (dry run)
+----
+
+Running `oc` with the `--dry-run=client` switch does not succeed with an invalid YAML file.
+
 == Indicating Technology Preview features
 
 To indicate that a feature is in Technology Preview, include the `snippets/technology-preview.adoc` file in the feature's assembly or module to keep the supportability wording consistent across Technology Preview features. Provide a value for the `:FeatureName:` variable before you include this module.