Merge pull request #73514 from dfitzmau/more-info-xref-guideline

more-info-xref-guideline: Updating the doc_guidelines.adoc with for m…

Author: adellape

contributing_to_docs/doc_guidelines.adoc

@@ -364,10 +364,10 @@ An `include` directive must always be on its own line.
 
 .Standard module include syntax
 [source,text]
-====
-\include::modules/module-filename.adoc[leveloffset=+1] <1>
-====
-<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.
+----
+include::modules/module-filename.adoc[leveloffset=+1] <1>
+----
+<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.
 
 You can use `tag` attributes to link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions[define regions of a file and include by tag instead of the whole file.] This enables you to make conditional modifications to existing modules instead of duplicating content. When creating a tag, use a tag name that makes it easy to understand where the content defined will be included.
 
@@ -743,21 +743,86 @@ Replace all public IP addresses with an address from the following blocks. These
 There might be advanced networking examples that require specific IP addresses, or cloud provider-specific examples that require a public IP address. Contact a subject matter expert if you need assistance with replacing IP addresses.
 ====
 
+[id="links-conditionals-assemblies"]
 == Links, hyperlinks, and cross references
 Links can be used to cross-reference internal assemblies or send readers to external information resources for further reading.
 
-In OpenShift docs:
+In OpenShift Container Platform docs:
 
-* All links to internal content is created using `xref` and **must have an anchor ID**.
+* All links to internal content is created by using an `xref`, and each `xref` **must have an anchor ID**.
 * Only use `xref` in assemblies, not in modules.
-* All links to external websites are created using `link`.
-* Links between different distros, such as from ROSA to OpenShift Container Platform, are external links and not cross-references. These external links use `link` instead of `xref` and need to be in distro-specific files or conditionalized to apply to the relevant distros.
+* All links to external websites are created by using the `link` attribute.
+* Links between different distributions, or _distros_, such as from ROSA to OpenShift Container Platform, are external links and not cross-references. These external links use `link` instead of `xref` and must be in distro-specific files or a conditionalized state to apply to the relevant distros.
 
 [IMPORTANT]
 ====
-Do not split link paths across lines when wrapping text. This will cause issues with the doc builds.
+Do not split link paths across lines when wrapping text. This will cause issues with the documentation builds.
+====
+
+[id="lead-in-link-sentences"]
+=== Lead-in link sentences
+
+Using a lead-in link sentence that adheres to guidelines maintains consistency across OpenShift Container Platform documentation.
+
+==== Lead-in link sentence style for non-xref situations
+
+For situations where you cannot use the `xref` attribute, such as referencing a module within a module, ensure that you adhere to the following guidance for lead-in link sentences.
+
+* Use the following format when pointing to a section in the same document:
++
+[source,text,subs="+quotes"]
+----
+For more information, see "<section_name>".
+----
+
+* Wrap the `<section_name>` string in quotation marks. The section name can be the title of a module or an assembly.
+
+* Do not state "in the Additional Resources section" or other variants. Mentioning the `<section_name>` is enough to prompt a documentation user to find the section in the same document.
+
+==== Lead-in link sentence style for the xref attribute
+
+For situations where you can use the `xref` attribute, adhere to the following guidance:
+
+* When pointing to a section (module) that exists in the same document (assembly), create an _Additional resources_ section in the assembly file and then place the `xref` as a bulleted item under the _Additional resources_ section. For example:
++
+[source,text]
+----
+[role="_additional-resources"]
+.Additional resources
+* xref:../../../installing/installing_vsphere/installation-config-parameters-vsphere.adoc#installation-config-parameters-vsphere[Installation configuration parameters]
+----
+
+* When pointing to a link in a section (module) that exists in another OpenShift Container Platform document (assembly), use the following format:
++
+[source,text]
+----
+For more information on <topic>, see xref:<path_to_file>["<section_name>"] in _<document_name>_.
+----
+
+Note the quotation marks around `<section_name>` and the italics around `<document_name>`.
+
+For more information about using `xref`, see xref:links-conditionals-assemblies[Links, hyperlinks, and cross references].
+
+==== Lead-in link sentence style for the link attribute
+
+For situations where you can use the `link` attribute, adhere to the following guidance:
+
+* When pointing to a link that exists external to Red Hat's customer portal documentation, add the `link` attribute, and use the `<document_heading_name> (<document_source>)` format. For example:
++
+[source,text]
+----
+See link:https://aws.amazon.com/about-aws/global-infrastructure/localzones/features/[AWS Local Zones features] (AWS documentation).
+----
+
+[NOTE]
+====
+Certain Red Hat resources, such as Knowledgebase articles, exist in a separate server location to Red Hat customer portal documentation. For these resources, use the `link` attribute format.
+
+For more information, see link:https://redhat-documentation.github.io/supplementary-style-guide/#rh-kb-links[Links to Red Hat Knowledgebase articles] (Red Hat supplementary style guide for product documentation).
 ====
 
+For more information about using `link`, see xref:links-conditionals-assemblies[Links, hyperlinks, and cross references].
+
 === Example URLs
 To provide an example URL path that you do not want to render as a hyperlink, use this format:
 
@@ -1785,14 +1850,15 @@ Do not use a password format that matches the format of a real password. Documen
 |myapp
 |===
 
+[id="additional-resources-sections"]
 === Additional resources sections
 
 The following guidelines apply to all "Additional resources" sections:
 
 * You must include the `[role="_additional-resources"]` attribute declaration before the section heading.
 * You must not include paragraphs in the section. Use an unordered list.
 * The links and xrefs in the unordered list must contain minimal-length, human-readable text between the square brackets. This text is often the title of the linked page.
-* You must not include text outside of the square brackets.
+* You must not include text outside of the square brackets. Text outside the brackets does not effectively render in an additional resources section box for a document on the Customer Portal.
 
 Additionally, in an assembly, use `==` formatting for the section heading (`== Additional resources`). Use of this heading syntax at the assembly level indicates that the sections relate to the whole assembly. For example:
 
@@ -1815,6 +1881,16 @@ Only use `.` formatting (`.Additional resources`) in a module or to follow a mod
 * xref:../configuration/product-settings.adoc#installation-parameters_product-settings[Product installation configuration parameters]
 ----
 
+You can add link, hyperlinks, and cross references in either the _Additional resources_ section or the _Next steps_ section, but know the following differences:
+
+Additional resources - module level:: Requires the `.Additional resources` section heading. The listed resources link to other material closely related to the contents of the module. Focus on including the most relevant resources for the user, not a full list of possibly related resources.
+
+Additional resources - assembly level:: Requires the `== Additional resources` section heading with a unique anchor ID. If a resource applies to all of the modules in a user story, consider listing the resource in the _Additional resources_ section of the assembly file.
+
+Next steps:: Provide links to resources that contain instructions that might be useful to the user after they complete a module or assembly. Do not use the _Next steps_ section to provide detailed instructions to documentation users.
+
+For more information about section types, see link:https://redhat-documentation.github.io/modular-docs/#assembly-guidelines["Assembly guidelines"] in the _Modular documentation reference guide_.
+
 == Admonitions
 Admonitions such as notes and warnings are formatted as shown:
 
@@ -2152,7 +2228,7 @@ a|
 
 |Table style operators
 
-|A style operator styles the content of a table cell or a table column, depending on where you set the operator. Using the literal (`l`) operator in a column might impact the documentation platform's copy and paste functionality. For example, when you paste copied code block content to a location, the first styled literal value in an assembly is pasted instead of the intended code block. To avoid this issue, use the monospace (`m`) style operator. When using any style operator in a table, check all copy and paste functions that follow the defined style operator work correctly for all code blocks in an assembly.
+|A style operator styles the content of a table cell or a table column, depending on where you set the operator. Using the literal (`l`) operator in a column might impact the documentation platform's copy and paste functionality. For example, when you paste copied code block content to a location, the first styled literal value in an assembly is pasted instead of the intended code block. When using any style operator in a table, check all copy and paste functions that follow the defined style operator work correctly for all code blocks in an assembly.
 
 See link:https://docs.asciidoctor.org/asciidoc/latest/tables/format-cell-content/[Cell styles and their operators] (Asciidoctor Documentation)