Merge pull request #81460 from apinnick/move-optional-heading-guideline

Contributing to docs: assembly/module file metadata improvements

Author: apinnick

contributing_to_docs/doc_guidelines.adoc

@@ -33,20 +33,30 @@ In the Pulsar editor, you can use `Ctrl`+`J` to undo hard wrapping on a paragrap
 
 [id="assembly-file-metadata"]
 == Assembly file metadata
-Every assembly file should contain the following metadata at the top, with no line spacing in between, except where noted:
+Every assembly file must contain the following metadata at the top, with no blank lines, except where noted:
 
 ----
 :_mod-docs-content-type: ASSEMBLY                               <1>
-[id="<unique_heading_for_assembly>"]                            <2>
+[id="<assembly-anchor-id>"]                                     <2>
 = Assembly title                                                <3>
 include::_attributes/common-attributes.adoc[]                   <4>
-:context: <unique_context_for_assembly>                         <5>
+:context: <assembly-context>                                    <5>
                                                                 <6>
 toc::[]                                                         <7>
 ----
 <1> The content type for the file. For assemblies, always use `:_mod-docs-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 and hyphens, for example: `cli-developer-commands`.
 <3> Human readable title (notice the `=` top-level header).
++
+[NOTE]
+====
+* Do not use backticks or other markup in assembly headings. You can use backticks or other markup in the title for a block, such as a code block `.Example` or a table `.Description` title.
+* Do not use "Optional:" to prefix an assembly title. According to IBM Style Guide, this practice is reserved for optional steps and code callouts.
+* With content reuse and modular documentation, you cannot be certain that all future use of an assembly will remain optional. For more information, see link:https://www.ibm.com/docs/en/ibm-style?topic=format-procedures#indicating-optional-and-conditional-steps["Indicating optional and conditional steps (Requires IBM Style login)"].
+* The assembly title, which is the first line of the document, is the only level 1 ( `=` ) title.
+Section headers within the assembly must be level 2 ( `==` ) or lower. When you include modules, you must add leveloffsets in the include statements. You can manually add more level 2 or lower section headers in the assembly.
+====
+
 <4> Includes attributes common to OpenShift docs.
 +
 [NOTE]
@@ -56,34 +66,22 @@ toc::[]                                                         <7>
 +
 [source,text]
 ----
- :_mod-docs-content-type: ASSEMBLY
- include::_attributes/common-attributes.adoc[]
- [id="installing-ibm-cloud-private"]
- = Installing a private cluster on {ibm-cloud-title}
- :context: installing-ibm-cloud-private
+:_mod-docs-content-type: ASSEMBLY
+include::_attributes/common-attributes.adoc[]
+[id="installing-ibm-cloud-private"]
+= Installing a private cluster on {ibm-cloud-title}
+:context: installing-ibm-cloud-private
 
 toc::[]
 ----
 ====
 +
 <5> Context used for identifying headers in modules that is the same as the anchor ID. Use lowercase and hyphens, for 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.
-
-[NOTE]
-====
-* Do not use backticks or other markup in assembly or module headings. You can use backticks or other markup in the title for a block, such as a code block `.Example` or a table `.Description` title.
-* Do not use "Optional:" to prefix a heading title. According to IBM Style, this practice is reserved for optional steps and code callouts. With content reuse and modular documentation, you cannot be certain that all future use of a module will remain optional. For more information, see link:https://www.ibm.com/docs/en/ibm-style?topic=format-procedures#indicating-optional-and-conditional-steps["Indicating optional and conditional steps (Requires IBM Style login)"].
-====
-
++
 After the heading block and a single whitespace line, you can include any content for this assembly.
 
-[NOTE]
-====
-The assembly title, which is the first line of the document, is the only level 1 ( = ) title.
-Section headers within the assembly must be level 2 ( == ) or lower. When you include modules, you must add
-leveloffsets in the include statements. You can manually add more level 2 or lower section headers in the assembly.
-====
+<7> The table of contents for the current assembly.
 
 [id="module-file-metadata"]
 == Module file metadata
@@ -101,26 +99,15 @@ Every module should be placed in the modules folder and should contain the follo
 
 <1> List of assemblies in which this module is included.
 <2> The content type for the file. Replace `<TYPE>` with the actual type of the module, `CONCEPT`, `REFERENCE`, or `PROCEDURE`. Place this attribute before the anchor ID or, if present, the conditional that contains the anchor ID.
-<3> A module anchor with {context} that must be lowercase and must match the module's file name.
-<4> Human readable title. To ensure consistency in the results of the
-leveloffset values in include statements, you must use a level one heading
+<3> The anchor ID with `_{context}` must be lowercase and match the module's file name.
+<4> Human readable title. To ensure consistency in the results of the leveloffset values in include statements, you must use a level 1 heading
 ( = ) for the module title.
-
-Example:
-
-----
-// Module included in the following assemblies:
-//
-// * cli_reference/openshift_cli/developer-cli-commands.adoc
-
-:_mod-docs-content-type: REFERENCE
-[id="cli-basic-commands_{context}"]
-= Basic CLI commands
-----
-
++
 [NOTE]
 ====
-Do not use backticks or other markup in assembly or module headings. You can use backticks or other markup in the title for a block, such as a code block `.Example` or a table `.Description` title.
+* Do not use backticks or other markup in module headings. You can use backticks or other markup in the title for a block, such as a code block `.Example` or a table `.Description` title.
+* Do not use "Optional:" to prefix a module title. According to IBM Style, this practice is reserved for optional steps and code callouts.
+* With content reuse and modular documentation, you cannot be certain that all future use of a module will remain optional. For more information, see link:https://www.ibm.com/docs/en/ibm-style?topic=format-procedures#indicating-optional-and-conditional-steps["Indicating optional and conditional steps (Requires IBM Style login)"].
 ====
 
 [id="snippet-file-metadata"]