Merge pull request #71472 from adellape/guidelines_1

Clarify subsection ID syntax in assemblies

Author: adellape

contributing_to_docs/doc_guidelines.adoc

@@ -9,7 +9,7 @@ link:https://redhat-documentation.github.io/modular-docs/[_Red Hat modular docs
 
 [NOTE]
 ====
-These _Documentation guidelines_ are primarily concerned with the modular structure and AsciiDoc / AsciiBinder requirements for building OpenShift documentation. For general style guidelines in OpenShift docs, see the following:
+These _Documentation guidelines_ are primarily concerned with the modular structure and AsciiDoc/AsciiBinder requirements for building OpenShift documentation. For general style guidelines in OpenShift docs, see the following:
 
 * Primary source: link:https://www.ibm.com/docs/en/ibm-style[_IBM Style_]
 * Supplementary source: link:https://redhat-documentation.github.io/supplementary-style-guide/[_Red Hat supplementary style guide for product documentation_]
@@ -36,17 +36,17 @@ In the Pulsar editor, you can use `Ctrl`+`J` to undo hard wrapping on a paragrap
 Every assembly file should contain the following metadata at the top, with no line spacing in between, except where noted:
 
 ----
-:_mod-docs-content-type: ASSEMBLY                                        <1>
-[id="<unique-heading-for-assembly>"]                            <2>
+:_mod-docs-content-type: ASSEMBLY                               <1>
+[id="<unique_heading_for_assembly>"]                            <2>
 = Assembly title                                                <3>
 include::_attributes/common-attributes.adoc[]                   <4>
-:context: <unique-context-for-assembly>                         <5>
+:context: <unique_context_for_assembly>                         <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. Example: cli-developer-commands
-<3> Human readable title (notice the `=` top-level header)
+<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).
 <4> Includes attributes common to OpenShift docs.
 +
 [NOTE]
@@ -66,8 +66,8 @@ toc::[]
 ----
 ====
 +
-<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.
+<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]
@@ -269,7 +269,7 @@ If you accidentally create an incorrect symbolic link, you can remove that link
 [openshift_cli ~]$ unlink images
 ----
 
-== Assembly/Module titles and section headings
+== Assembly/module titles and section headings
 
 Use sentence case in all titles and section headings. See http://www.titlecase.com/ or https://convertcase.net/ for a conversion tool.
 
@@ -287,98 +287,126 @@ Do not use backticks or other markup in assembly or module headings.
 
 Do not use special characters or symbols in titles. Symbols and special characters in titles can cause rendering errors in the HTML output.
 
-Use only one level 1 heading (`=`) in any file.
+Use only one link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax[Level 0] heading (`=`) in any file.
 
-=== Discrete headings
+=== Anchoring titles and section headings
 
-If you have a section heading that you do not want to appear in the TOC (like if you think that some section is not worth showing up or if there are already too many nested levels), you can use a discrete (or floating) heading:
+All titles and section headings must have an anchor ID. The anchor ID must be similar to the title or section heading. Do not include line spaces between the anchor ID and the section title.
 
-https://docs.asciidoctor.org/asciidoc/latest/blocks/discrete-headings/
+.Example anchor ID and heading
+----
+[id="configuring-alert-notifications"] <1>
+= Configuring alert notifications <2>
+----
+<1> Anchor ID
+<2> Title/section heading
 
-A discrete heading also will not get a section number in the Customer Portal build of the doc. Previously, we would use plain bold mark-up around a heading like this, but discrete headings also allow you to ignore section nesting rules (like jumping from a `==` section level to a `====` level if you wanted for some style reason).
+The following anchor IDs also require use of the `_{context}` variable:
 
-To use a discrete heading, just add `[discrete]` to the line before your unique ID. For example:
+* **All** headings in module files
+* **Only** subsections in assembly files (but not the link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax[Level 0] heading/main title)
 
-----
-[discrete]
-[id="managing-authorization-policies_{context}"]
-== Managing authorization policies
-----
+When called, the `_{context}` variable is resolved into the value declared in the `:context:` attribute in the corresponding assembly file. This enables cross-referencing of IDs in context to a specific assembly and is useful when a module is included in multiple assemblies.
 
-== Anchoring titles and section headings
+[NOTE]
+====
+The `{context}` variable must be preceded by an underscore (`_`) when declared in an anchor ID.
+====
 
-All titles and section headings must have an anchor ID. The anchor ID must be similar to the title or section heading.
+==== Anchoring in assembly files
 
-=== Anchoring in assembly files
+===== Assembly titles (Level 0 headings)
 
-The following is an example anchor ID in an assembly file:
+For the single link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax[Level 0] heading (`=`) of an assembly file, **do not** add a `_{context}` variable to the end of the anchor ID.
 
+.Example anchor ID for the Level 0 heading of an assembly file
 ----
 [id="configuring-alert-notifications"]
 = Configuring alert notifications
 ----
 
 [NOTE]
 ====
-Do not include line spaces between the anchor ID and the section title.
+This guideline includes an exception to the link:https://redhat-documentation.github.io/modular-docs/#nesting-assemblies[_Red Hat modular docs reference guide_], which shows including the `{context}` variable for Level 0 headings of assemblies as well.
 ====
 
-=== Anchoring in module files
+The anchor ID for the assembly title should match the `:context:` set in the xref:assembly-file-metadata[assembly file metadata].
 
-You must add the `{context}` variable to the end of each anchor ID in module files. When called, the `{context}` variable is resolved into the value declared in the `:context:` attribute in the corresponding assembly file. This enables cross-referencing to module IDs in context to a specific assembly and is useful when a module is included in multiple assemblies.
+===== Assembly subsections (Level 1 and lower headings)
 
-[NOTE]
-====
-The `{context}` variable must be preceded by an underscore (`_`) when declared in an anchor ID.
-====
+For any Level 1 or lower _subsections_ in an assembly (for example, `==`, `===`, etc.), add a `_{context}` variable to the end of anchor IDs:
 
-The following is an example of an anchor ID for a module file title:
+.Example anchor ID for a Level 1 heading (subsection) of an assembly file
+----
+[id="editing-alerts_{context}"]
+== Editing alerts
+----
 
+This ensures a unique anchor ID across the repo.
+
+==== Anchoring in module files
+
+You must add the `_{context}` variable to the end of each anchor ID in module files, for any section level:
+
+.Example anchor ID for a module file Level 0 (`=`) heading/main title
 ----
 [id="sending-notifications-to-external-systems_{context}"]
 = Sending notifications to external systems
 ----
 
-The following is an example of an anchor ID for a second level (`==`) heading:
-
+.Example anchor ID for a Level 1 (`==`) subsection heading
 ----
 [id="deployment-scaling-benefits_{context}"]
 == Deployment and scaling benefits
 ----
 
 === Anchoring "Prerequisites", "Additional resources", and "Next steps" titles in assemblies
 
-Use unique IDs for "Prerequisites", "Additional resources", and "Next steps" titles in assemblies. You can add the prefixes `prerequisites_`, `additional-resources_`, or `next-steps_` to a unique string that describes the assembly topic. The unique string can match the value assigned to the `:context:` attribute in the assembly.
-
-[NOTE]
-====
-The `prerequisites_`, `additional-resources_`, and `next-steps_` prefixes must end with an underscore (`_`) when declared in an anchor ID in an assembly.
-====
-
-The following examples include IDs that are unique to the "Configuring alert notifications" assembly:
-
-*Example unique ID for a "Prerequisites" title*
+For anchor IDs of "Prerequisites", "Additional resources", and "Next steps" titles in assemblies, use the prefixes `prerequisites_`, `additional-resources_`, or `next-steps_` followed by the `{context}` variable. Using this variable automatically matches the value assigned to the `:context:` attribute in the assembly, which ensures a unique ID across the repo. Use an underscore (`_`) between the prefix and `{context}` variable.
 
+.Example unique anchor ID for a "Prerequisites" title
 ----
-[id="prerequisites_configuring-alert-notifications"]
+[id="prerequisites_{context}"]
 == Prerequisites
 ----
 
-*Example unique ID for an "Additional resources" title*
-
+.Example unique anchor ID for an "Additional resources" title
 ----
 [role="_additional-resources"]
-[id="additional-resources_configuring-alert-notifications"]
+[id="additional-resources_{context}"]
 == Additional resources
 ----
 
-*Example unique ID for a "Next steps" title*
-
+.Example unique anchor ID for a "Next steps" title
 ----
-[id="next-steps_configuring-alert-notifications"]
+[id="next-steps_{context}"]
 == Next steps
 ----
 
+=== Discrete headings
+
+If you have a section heading that you do not want to appear in the TOC (for example, if you think that some section is not worth showing up or if there are already too many nested levels), you can use a discrete (or floating) heading:
+
+https://docs.asciidoctor.org/asciidoc/latest/blocks/discrete-headings/
+
+A discrete heading also will not get a section number in the Customer Portal build of the doc. Previously, we would use plain bold mark-up around a heading like this, but discrete headings also allow you to ignore section nesting rules (like jumping from a `==` section level to a `====` level if you wanted for some style reason).
+
+To use a discrete heading, add `[discrete]` to the line before your unique ID:
+
+.Example in a module
+----
+[discrete]
+[id="managing-authorization-policies_{context}"]
+== Managing authorization policies
+----
+
+.Example in an assembly
+----
+[discrete]
+[id="olm-restricted-networks-mirroring-catalog"]
+== Mirroring a catalog
+----
+
 == Writing assemblies
 An _assembly_ is a collection of modules that describes how to accomplish a user story. Module content is added to an assembly using the `include` directive. The `include` directive includes contents from another file in the current document. Files can be modules or snippets formatted in AsciiDoc, or another text format such as YAML.
 
@@ -748,7 +776,7 @@ Some provider-formatted hostnames include IPv4 addresses. An OpenShift Container
 
 == IP addresses
 
-You may include IPv4 addresses from test clusters in examples in the documentation, as long as they are private. Private IPv4 addresses fall into one of the following ranges:
+You may include IPv4 addresses from test clusters in examples in the documentation, provided that they are private. Private IPv4 addresses fall into one of the following ranges:
 
 * 10.0.0.0 to 10.255.255.255 (class A address block 10.0.0.0/8)
 * 172.16.0.0 to 172.31.255.255 (class B address block 172.16.0.0/12)
@@ -1173,7 +1201,7 @@ docker-registry     <none>                                    name=registrypod
 ....
 +
 This renders as:
-
++
 > In the following example, the `oc get` operation returns a complete list of services that are currently defined:
 >
 > ----
@@ -1886,7 +1914,7 @@ Additionally, in an assembly, use `==` formatting for the section heading (`== A
 
 ----
 [role="_additional-resources"]
-[id="additional-resources_configuring-alert-notifications"]
+[id="additional-resources_{context}"]
 == Additional resources
 * link:example.com[IANA example domain for documentation]
 * xref:../installation/installing-the-product.adoc#installing-the-product[Installing the product]
@@ -2202,7 +2230,7 @@ a|
 >
 > `oc apply -f <path_to_configuration_file>/<filename>.yaml`
 
-|Use single asterisks for web console / GUI items (menus, buttons, page titles, etc.).
+|Use single asterisks for web console/GUI items (menus, buttons, page titles, etc.).
 Use two characters to form the arrow in a series of menu items (`$$->$$`).
 
 a|