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`.
@@ -56,8 +58,8 @@ toc::[]                                                         <7>
 * 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.
+<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
@@ -274,7 +279,9 @@ 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] (maps to an H1 or `<h1>` in HTML) heading (`=`) in any file.
+
+Do not use H3 headings (`===`) or lower in any files.
 
 === Anchoring titles and section headings
 
@@ -319,9 +326,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 +338,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 +406,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 +550,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,25 +572,25 @@ 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-4.8` and earlier enterprise versions
+// |Control plane (also known as master) node
 
-|`enterprise-3.11`
-|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.
-====
+// [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 +1908,70 @@ 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.
+// 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.
+// =====
+// ====
 
 === Quick reference