diff --git a/contributing_to_docs/doc_guidelines.adoc b/contributing_to_docs/doc_guidelines.adoc
index ab5b89d9946c..d4ca139e95bb 100644
--- a/contributing_to_docs/doc_guidelines.adoc
+++ b/contributing_to_docs/doc_guidelines.adoc
@@ -744,56 +744,39 @@ IMPORTANT: You must use `link:` before the start of the URL.
 
 IMPORTANT: You cannot link to a repository that is hosted on www.github.com.
 
-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.
+TIP: If you want to build a link from a URL _without_ changing the text from the actual URL, print the URL without adding a `[friendly text]` block at the end; it will automatically render as a link.
 
 === Links to internal content
-There are two scenarios for linking to other assemblies:
 
-1. Link to another file that exists in the same directory.
-2. Link to another file that exists in a separate directory.
-
-The following examples use the example directory structure shown here:
-....
-/
-/foo
-/foo/bar.adoc
-/baz
-/baz/zig.adoc
-/baz/zag.adoc
-....
-
-*Link to assembly in same directory*
+If you want to link to other assemblies or modules in the repository, use the following format:
 
 ----
-xref:<filename>#anchor-id[friendly title]
+xref:../<dir>/<assembly_name>.adoc#<anchor_id>[<section_title>]
 ----
 
-You must use the `.adoc` file extension. The document processor will correctly link this to the resulting HTML file.
-
-For example, using the above syntax, if you are working on `zig.adoc` and want to link to `zag.adoc`, do it this way:
-
-----
-xref:../zag.adoc#baz-zag[comment]
-----
+Note the following guidelines:
 
-where `baz-zag` is the anchor ID at the top of the file `zag.adoc`.
+* You must use the `.adoc` extension.
+* You must specify an anchor ID.
+* You must back up the appropriate number of levels (`../`, `../../`, and so on) to get back to the top-level `openshift-docs/` repository, and then specify the subdirectories to get back down to the assembly.
 
-*Link to assembly in different directory*
+For example, if you have the following directory structure:
 
-----
-xref:../dir/<filename>.adoc#anchor-id[friendly title]
-----
+....
+openshift-docs/
+openshift-docs/foo
+openshift-docs/foo/bar.adoc
+openshift-docs/baz
+openshift-docs/baz/zig.adoc
+....
 
-For example, if you are working on `bar.adoc` and you want to link to `zig.adoc`, do it this way:
+And you are working in `bar.adoc` and want to link to `zig.adoc`, use the following xref:
 
 ----
 For more information, see the xref:../baz/zig.adoc#baz-zig[ZIG manual].
 ----
 
-[NOTE]
-====
-You must use the `.adoc` extension in order for the link to work correctly and you must specify an anchor ID.
-====
+where `baz-zig` is the anchor ID.
 
 == Embedding an external file