Merge pull request #96408 from jeana-redhat/migration-compatible-metadata-sample

Updates samples for migration, removes stale guidelines

Author: jeana-redhat

contributing_to_docs/doc_guidelines.adoc

@@ -39,10 +39,12 @@ Every assembly file must contain the following metadata at the top, with no blan
 :_mod-docs-content-type: ASSEMBLY                               <1>
 [id="<assembly-anchor-id>"]                                     <2>
 = Assembly title                                                <3>
-include::_attributes/common-attributes.adoc[]                   <4>
-:context: <assembly-context>                                    <5>
+                                                                <4>
+include::_attributes/common-attributes.adoc[]                   <5>
                                                                 <6>
-toc::[]                                                         <7>
+:context: <assembly-context>                                    <7>
+                                                                <8>
+toc::[]                                                         <9>
 ----
 <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`.
@@ -54,10 +56,10 @@ toc::[]                                                         <7>
 * 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.
+Section headers within the assembly must be H2 ("Level 1" in AsciiDoc terminology), formatted as `==`. When you include modules, you must add leveloffsets in the include statements. You can manually add more H2 (`==`) section headers in the assembly.
 ====
-
-<4> Includes attributes common to OpenShift docs.
+<4> You must include a blank line after H1 ("Level 0" in AsciiDoc terminology) headings.
+<5> Includes attributes common to OpenShift docs.
 +
 [NOTE]
 ====
@@ -68,20 +70,21 @@ Section headers within the assembly must be level 2 ( `==` ) or lower. When you
 ----
 :_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::[]`.
+<6> You must include a blank line after each `include::` statement.
+<7> Context used for identifying headers in modules that is the same as the anchor ID. Use lowercase and hyphens, for example `cli-developer-commands`.
+<8> A blank line. You *must* have a blank line here before the `toc::[]`.
 +
 After the heading block and a single whitespace line, you can include any content for this assembly.
-
-<7> The table of contents for the current assembly.
+<9> The table of contents for the current assembly.
 
 [id="module-file-metadata"]
 == Module file metadata
@@ -95,6 +98,7 @@ Every module should be placed in the modules folder and should contain the follo
 :_mod-docs-content-type: <TYPE>                                    <2>
 [id="<module-anchor>_{context}"]                                   <3>
 = Module title                                                     <4>
+                                                                   <5>
 ----
 
 <1> List of assemblies in which this module is included.
@@ -109,6 +113,7 @@ Every module should be placed in the modules folder and should contain the follo
 * 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)"].
 ====
+<5> You must include a blank line after H1 ("Level 0" in AsciiDoc terminology) headings.
 
 [id="snippet-file-metadata"]
 == Text snippet file metadata
@@ -260,9 +265,7 @@ If you accidentally create an incorrect symbolic link, you can remove that link
 
 Use sentence case in all titles and section headings. See http://www.titlecase.com/ or https://convertcase.net/ for a conversion tool.
 
-Try to be as descriptive as possible with the title or section headings
-without making them unnecessarily long. For assemblies and task modules,
-use a gerund form in headings, such as:
+Try to be as descriptive as possible with the title or section headings without making them unnecessarily long. For assemblies and task modules, use a gerund form in headings, such as:
 
 * Creating
 * Managing
@@ -274,7 +277,10 @@ 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 link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax[Level 0] 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. 
+Level 0 headings map to an H1 or `<h1>` in HTML.
+
+Do not use Level 2 (H3) headings (`===`) or lower in any files.
 
 === Anchoring titles and section headings
 
@@ -319,9 +325,9 @@ This guideline includes an exception to the link:https://redhat-documentation.gi
 
 The anchor ID for the assembly title should match the `:context:` set in the xref:assembly-file-metadata[assembly file metadata].
 
-===== Assembly subsections (Level 1 and lower headings)
+===== Assembly subsections (Level 1 headings)
 
-For any Level 1 or lower _subsections_ in an assembly (for example, `==`, `===`, etc.), add a `_{context}` variable to the end of anchor IDs:
+For any Level 1 _subsections_ in an assembly (i.e. `==`), add a `_{context}` variable to the end of anchor IDs:
 
 .Example anchor ID for a Level 1 heading (subsection) of an assembly file
 ----
@@ -331,6 +337,8 @@ For any Level 1 or lower _subsections_ in an assembly (for example, `==`, `===`,
 
 This ensures a unique anchor ID across the repo.
 
+Do not use H3 headings (`===`) or lower in any files.
+
 ==== Anchoring in module files
 
 You must add the `_{context}` variable to the end of each anchor ID in module files, for any section level:
@@ -397,14 +405,16 @@ To use a discrete heading, add `[discrete]` to the line before your unique ID:
 == 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.
 
-An `include` directive must always be on its own line.
+An `include` directive must always be on its own line and be followed by a blank line.
 
 .Standard module include syntax
 [source,text]
 ----
 include::modules/module-filename.adoc[leveloffset=+1] <1>
+                                                      <2>
 ----
 <1> `[leveloffset=]` link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/#manipulate-heading-levels-with-leveloffset[is relative], and changes the header level of included content.
+<2> You must include a blank line after each `include::` statement.
 
 [IMPORTANT]
 ====
@@ -539,9 +549,9 @@ For more information about creating text snippets, see the
 link:https://redhat-documentation.github.io/modular-docs/#using-text-snippets[_Red Hat modular docs reference guide_].
 
 [id="Auto-generated-content"]
-== Auto-generated content
+== Automatically generated content
 
-The following content is auto-generated in each release and must not be manually edited:
+The following content is automatically generated in each release and must not be manually edited:
 
 * The OpenShift CLI (`oc`) command references `modules/oc-by-example-content.adoc` and `modules/oc-adm-by-example-content.adoc`.
 * The following API references content in the `rest_api` folder: the contents of all `<topic>_apis` subfolders and the `rest_api/objects/index.adoc` and `rest_api/index.adoc` assemblies.
@@ -561,26 +571,15 @@ To assist with the removal of the problematic word "master" from the documentati
 |===
 |Branch |Control plane node reference
 
-|`main`, `enterprise-4.9`, and later enterprise versions
+|All supported versions
 |Control plane node
 
-|`enterprise-4.8` and earlier enterprise versions
-|Control plane (also known as master) node
-
-|`enterprise-3.11`
-|Master node
-
 |===
 
 You can replace "node" in the preceding examples with "machine", "host", or another suitable description.
 
 In general text, use the term "control plane machine" in place of "master machine"; use the term "compute machine" in place of "worker machine". Be mindful of certain valid code entities, such as `master` role, `worker` role, and `infra` role.
 
-[NOTE]
-====
-If you are cherry picking from `main` to `enterprise-4.8` or earlier, you must manually cherry pick to include the “(also known as master)” phrasing. This is required only if the phrase “control plane” is introduced for the first time in an assembly or module.
-====
-
 [id="adding-a-subsection-on-making-open-source-more-inclusive"]
 === Adding a subsection on making open source more inclusive
 
@@ -1897,68 +1896,8 @@ The notes immediately follow the table, instead of appearing at the bottom of th
 
 [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.
 
-[NOTE]
-====
-You must set a title for the `summary` section. If a title is not set, the default title is "Details."
-====
-
-Collapsible content is formatted as shown:
-
-....
-.Title of the `summary` dropdown
-[%collapsible]
-====
-This is content within the `details` section.
-====
-....
-
-This renders as a dropdown with collapsed content:
-
-.Title of the `summary` dropdown
-[%collapsible]
-====
-This is content within the `details` section.
-====
-
-If your collapsible content includes an admonition such as a note or warning, the admonition must be nested:
-
-....
-.Collapsible content that includes an admonition
-[%collapsible]
-====
-This content includes an admonition.
-
-[source,terminal]
-----
-$ oc whoami
-----
-
-[NOTE]
-=====
-Nest admonitions when using the `collapsible` option.
-=====
-====
-....
-
-This renders as:
-
-.Collapsible content that includes an admonition
-[%collapsible]
-====
-This content includes an admonition.
-
-[source,terminal]
-----
-$ oc whoami
-----
-
-[NOTE]
-=====
-Nest admonitions when using the `collapsible` option.
-=====
-====
+Creating  collapsible sections of content by using the `collapsible` option is not supported by our publication tooling.
 
 === Quick reference