Merge pull request #89394 from ShaunaDiaz/OSDOCS-13518

OSDOCS-13518: adds clarification on xrefs for snippets

Author: ShaunaDiaz

contributing_to_docs/doc_guidelines.adoc

@@ -490,19 +490,31 @@ A _procedure_ contains the steps that users follow to complete a single process
 
 Use a gerund in the procedure title, such as "Creating".
 
+[IMPORTANT]
+====
+Modules cannot contain xrefs. If you _must_ use a link in your module, use the `link` attribute type and treat it as an external reference.
+
+Use version attributes for the maintainability of xrefs and links whenever you can.
+====
+
 For more information about writing procedures, see the
 link:https://redhat-documentation.github.io/modular-docs/#con-creating-procedure-modules_writing-mod-docs[_Red Hat modular docs reference guide_] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc[procedure template].
 
 [NOTE]
 ====
-When needed, use `.Prerequisites`, `.Next steps`, or `.Additional resources` syntax to suppress TOC formatting within a module. Do not use `==` syntax for these headings in modules. Because you cannot use the xrefs in modules, if you need to include a link under one of these headings, place the entire subsection in the assembly instead.
+When needed, use the _<.section_title>_ syntax suppress TOC formatting within a module, for example, `.Prerequisites`, `.Procedure`, `.Next steps`, or `.Additional resources`. Do not use the heading-level syntax, such as `==`, for these headings in modules.
 ====
 
 [id="writing-text-snippets"]
 == Writing text snippets
 A _text snippet_ is an optional component that lets you reuse content in multiple modules and assemblies. Text snippets are not a substitute for modules but instead are a more granular form of content reuse. While a module is content that a reader can understand on its own (like an article) or as part of a larger body of work (like an assembly), a text snippet is not self-contained and is not intended to be published or cross referenced on its own.
 
-In the context of modules and assemblies, text snippets do not include headings or anchor IDs. Text snippets also cannot contain xrefs. This type of component is text only. Examples include the following:
+[IMPORTANT]
+====
+Like modules, text snippets cannot contain xrefs. If you _must_ use a link in your snippet, use the `link` attribute type and treat it as an external reference. It is recommended to use version attributes for maintainability of the link.
+====
+
+In the context of modules and assemblies, text snippets do not include headings or anchor IDs. Examples include the following:
 
 * Admonitions that appear in multiple modules.
 * An introductory paragraph that appears in multiple assemblies.
@@ -827,7 +839,7 @@ Links can be used to cross-reference internal assemblies or send readers to exte
 In OpenShift Container Platform docs:
 
 * 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.
+* Only use `xref` in assemblies, not in modules or snippets.
 * 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.