openshiftGH-53958: Fix xref guidelines for contrib doc

Fix xref guidelines for contrib doc, make 1 scenario

Fix xref guidelines for contrib doc, make 1 scenario

openshiftGH-53958: Fix xref guidelines for contrib doc

As called out in the comments: openshift#53958

This updates the `/baz/zig` and `/baz/zag` examples.

@openshift/team-documentation PTAL

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/test1
+openshift-docs/test1/test2.adoc
+openshift-docs/test3
+openshift-docs/test3/example1.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 `test2.adoc` and want to link to `example1.adoc`, use the following xref:
 
 ----
-For more information, see the xref:../baz/zig.adoc#baz-zig[ZIG manual].
+For more information, see the xref:../test3/example1.adoc#test3-example1[EXAMPLE1 manual].
 ----
 
-[NOTE]
-====
-You must use the `.adoc` extension in order for the link to work correctly and you must specify an anchor ID.
-====
+where `test3-example1` is the anchor ID.
 
 == Embedding an external file