Merge pull request #63850 from rohennes/revert-include-position-add-note

Reverting include positioning updates

Author: kalexand-rh

contributing_to_docs/doc_guidelines.adoc

@@ -1,6 +1,7 @@
 [id="contributing-to-docs-doc-guidelines"]
-include::_attributes/common-attributes.adoc
 = Documentation guidelines
+include::_attributes/common-attributes.adoc
+
 :toc: macro
 
 The documentation guidelines for OpenShift 4 build on top of the
@@ -37,23 +38,23 @@ Every assembly file should contain the following metadata at the top, with no li
 ----
 :_content-type: ASSEMBLY                                        <1>
 [id="<unique-heading-for-assembly>"]                            <2>
-include::_attributes/common-attributes.adoc[]                   <3>
-= Assembly title                                                <4>
+= Assembly title                                                <3>
+include::_attributes/common-attributes.adoc[]                   <4>
 :context: <unique-context-for-assembly>                         <5>
                                                                 <6>
 toc::[]                                                         <7>
 ----
-
 <1> The content type for the file. For assemblies, always use `:_content-type: ASSEMBLY`. Place this attribute before the anchor ID or, if present, the conditional that contains the anchor ID.
-<2> A unique (within OpenShift docs) anchor ID for this assembly. Use lowercase. Example: cli-developer-commands.
-<3> Includes attributes common to OpenShift docs.
+<2> A unique (within OpenShift docs) anchor ID for this assembly. Use lowercase. Example: cli-developer-commands
+<3> Human readable title (notice the `=` top-level header)
+<4> Includes attributes common to OpenShift docs.
 +
 [NOTE]
 ====
-The `{product-title}` 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 title and version] and xref:attribute-files[attribute files] for more information on this topic.
+* The `{product-title}` 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 title and version] and xref:attribute-files[attribute files] for more information on this topic.
+* If you use a variable in the title of the first assembly in a section, move the include attributes directive above the title in this assembly. Otherwise, the variable will not render correctly on access.redhat.com.
 ====
 +
-<4> Human readable title (notice the `=` top-level header).
 <5> Context used for identifying headers in modules that is the same as the anchor ID. Example: cli-developer-commands.
 <6> A blank line. You *must* have a blank line here before the toc.
 <7> The table of contents for the current assembly.