Merge pull request #102280 from bergerhoffer/updating-for-xrefs-in-rns

Noting xref in module exception for release notes

Author: bergerhoffer

contributing_to_docs/doc_guidelines.adoc

@@ -438,8 +438,9 @@ 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.
+Most modules cannot contain xrefs. If you must include a link in a module, use the `link` attribute type and treat it as an external reference. The only exception is release notes modules, which may contain xrefs as long as the module is included in only one location.
 
+// TODO: Check w/ Jeana on updating this:
 Use version attributes for the maintainability of xrefs and links whenever you can.
 ====
 
@@ -457,7 +458,8 @@ A _text snippet_ is an optional component that lets you reuse content in multipl
 
 [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.
+// TODO: Jeana:
+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:
@@ -829,6 +831,11 @@ 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 or snippets.
++
+[IMPORTANT]
+====
+Exception: You may use cross-references (`xref`) in modules only for release notes. The module must only ever be included once from one assembly.
+====
 * 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.
 
@@ -950,12 +957,12 @@ IMPORTANT: You cannot link to a repository that is hosted on www.github.com. An
 TIP: If you want to build a link from a URL _without_ changing the text from the actual URL, just print the URL without adding a `[friendly text]` block at the end; it will automatically be rendered as a link.
 
 ==== Guidance for including outside sources
-In general, avoid linking to sources outside of an official Red Hat domain whenever possible. 
+In general, avoid linking to sources outside of an official Red Hat domain whenever possible.
 
-Some acceptable exceptions to this rule include: 
+Some acceptable exceptions to this rule include:
 
-1. Links to third-party product documentation when it would be otherwise unreasonable or impossible to write procedures using another product. 
-2. Upstream resources for a feature or component based on an upstream project when re-writing the resource for downstream use would be too arduous to write for too little value, or too difficult to maintain. 
+1. Links to third-party product documentation when it would be otherwise unreasonable or impossible to write procedures using another product.
+2. Upstream resources for a feature or component based on an upstream project when re-writing the resource for downstream use would be too arduous to write for too little value, or too difficult to maintain.
 3. Upstream API references
 
 If you feel you need to link to an outside source, discuss it with a content strategist, and then make sure you have approval from your PM and engineering stakeholders and the Product Operations team member who works in your area.