Merge pull request #32990 from bergerhoffer/declarative-contrib

Guidelines for adding declarative YAML examples to procedures

Author: bergerhoffer

contributing_to_docs/doc_guidelines.adoc

@@ -1062,6 +1062,7 @@ Note the following:
 * To match the table cell's font size, start the ordered list with a `[.small]`
 style and wrap it in a `--` block.
 
+[id="collapsible-content"]
 === Collapsible content
 You can collapse sections of content by using the `collapsible` option, which converts the Asciidoctor markup to HTML `details` and `summary` sections. The `collapsible` option is used at the writer's discretion and is appropriate for considerably long code blocks, lists, or other such content that significantly increases the length of a module or assembly.
 
@@ -1262,6 +1263,74 @@ style guidelines. For example:
 - Node Tuning Operator
 - Cluster Version Operator
 
+== Declarative config examples
+
+Many of our procedures provide imperative `oc` commands (which cannot be stored in a Git repo). Due to efforts around improving the experience for GitOps users, we sometimes also want to provide a declarative YAML example that achieves the same configuration. This allows users to store these YAML configurations in a Git repo and follow GitOps practices to configure OpenShift.
+
+[IMPORTANT]
+====
+When adding declarative examples to procedures, do not completely replace the imperative command with the declarative YAML example. Some users might still prefer the imperative option.
+====
+
+To add a declarative YAML example to a procedure step with an existing imperative command, add it in a "TIP" admonition by following the template in the example below. This example uses an imperative command (`oc create configmap`) to create a config map, and then provides the declarative YAML example of the `ConfigMap` object afterward.
+
+....
+* Define a `ConfigMap` object containing the certificate authority by using the following command:
++
+[source,terminal]
+----
+$ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
+----
++
+[TIP]
+====
+You can alternatively apply the following YAML to create the config map:
+
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: ca-config-map
+  namespace: openshift-config
+type: Opaque
+data:
+  ca.crt: <base64_encoded_CA_certificate_PEM>
+----
+====
+....
+
+This renders as:
+
+> * Define a `ConfigMap` object containing the certificate authority by using the following command:
+> +
+> [source,terminal]
+> ----
+> $ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
+> ----
+> +
+> [TIP]
+> ====
+> You can alternatively apply the following YAML to create the config map:
+>
+> [source,yaml]
+> ----
+> apiVersion: v1
+> kind: ConfigMap
+> metadata:
+>   name: ca-config-map
+>   namespace: openshift-config
+> type: Opaque
+> data:
+>   ca.crt: <base64_encoded_CA_certificate_PEM>
+> ----
+> ====
+
+[NOTE]
+====
+If you are adding a particularly long YAML block, you can optionally use the xref:collapsible-content[`%collapsible`] feature to allow users to collapse the code block.
+====
+
 == Quick markup reference
 
 |===