Merge pull request openshift#42080 from kalexand-rh/attributes-guidelines

adding attribute file guidance

Author: kalexand-rh

contributing_to_docs/doc_guidelines.adoc

@@ -28,7 +28,7 @@ Every assembly file should contain the following metadata at the top, with no li
 :_content-type: ASSEMBLY                                        <1>
 [id="<unique-heading-for-assembly>"]                            <2>
 = Assembly title                                                <3>
-include::modules/common-attributes.adoc[]                       <4>
+include::_attributes/common-attributes.adoc[]                   <4>
 :context: <unique-context-for-assembly>                         <5>
                                                                 <6>
 toc::[]                                                         <7>
@@ -41,7 +41,7 @@ toc::[]                                                         <7>
 +
 [NOTE]
 ====
-The `{product-name}` and `{product-version}` common attributes are not defined in the `modules/common-attributes.adoc` file. Those attributes are pulled by AsciiBinder from the distro mapping definitions in the https://github.com/openshift/openshift-docs/blob/main/_distro_map.yml[_distro_map.yml] file. See xref:product-name-and-version[Product name and version] for more information on this topic.
+The `{product-name}` and `{product-version}` common attributes are not defined in the `_attributes/common-attributes.adoc` file. Those attributes are pulled by AsciiBinder from the distro mapping definitions in the https://github.com/openshift/openshift-docs/blob/main/_distro_map.yml[_distro_map.yml] file. See xref:product-name-and-version[Product name and version] and xref:attribute-files[attribute files] for more information on this topic.
 ====
 +
 <5> Context used for identifying headers in modules that is the same as the anchor ID. Example: cli-developer-commands.
@@ -147,6 +147,33 @@ Place the attribute in the file metadata. The following list describes the best
 
 The metadata examples contain sample placement for each file type, xref:assembly-file-metadata[assembly], xref:module-file-metadata[module], and xref:snippet-file-metadata[snippet].
 
+[id="attribute-files"]
+== Attribute files
+
+All attribute files must be placed in the `_attributes` directory. In most cases involving OpenShift Container Platform or OKD, add attributes to the `common-attributes.adoc` file instead of creating or using a separate attributes file. Before you add an attribute, review the contents of the `common-attributes.adoc` file to ensure that it is not already defined.
+
+[IMPORTANT]
+====
+If you think that you need a separate attributes file, check with the docs team before you create it.
+====
+
+It is acceptable to group related attributes in the `common-attributes.adoc` file under a comment, as shown in the following example:
+
+----
+//gitops
+:gitops-title: Red Hat OpenShift GitOps
+:gitops-shortname: GitOps
+----
+
+It is also acceptable to enclose attributes in a xref:product-name-and-version[distro-based] conditional. The following example shows how to set a different value for the `:op-system-base:` attribute for OKD:
+
+----
+:op-system-base: RHEL
+ifdef::openshift-origin[]
+:op-system-base: Fedora
+endif::[]
+----
+
 == Assembly/module file names
 
 Try to shorten the file name as much as possible _without_ abbreviating important terms that may cause confusion. For example, the `managing-authorization-policies.adoc` file name would be appropriate for an assembly titled "Managing Authorization Policies".
@@ -455,7 +482,7 @@ If it makes more sense in context to refer to the major version of the product i
 
 [NOTE]
 ====
-Other common attribute values are defined in the `modules/common-attributes.adoc` file. Where possible, generalize references to those values by using the common attributes. For example, use `{console-redhat-com}` to refer to Red Hat OpenShift Cluster Manager.
+Other common attribute values are defined in the `_attributes/common-attributes.adoc` file. Where possible, generalize references to those values by using the common attributes. For example, use `{console-redhat-com}` to refer to Red Hat OpenShift Cluster Manager. If you need to add an attribute to the `_attributes/common-attributes.adoc` file, open a pull request to add it to the attribute list. Do not create a separate attributes file without first consulting the docs team.
 ====
 
 [id="conditional-content"]