Merge pull request #31596 from bergerhoffer/updating-guidelines-symlinks

Updating guidelines to point out the required symbolic links

Author: bergerhoffer

contributing_to_docs/doc_guidelines.adoc

@@ -92,6 +92,36 @@ Try to shorten the file name as much as possible _without_ abbreviating importan
 
 If you create a directory with a multiple-word name, separate each word with an underscore, for example `backup_and_restore`. Do not create a top-level directory in the repository without checking with the docs team. In the main OpenShift docs, you can create one level of subdirectories. In the docs for features that are designed to be used with OpenShift, such as Service Mesh and OpenShift virtualization, you can create two levels of subdirectories.
 
+When creating a new directory or subdirectory, you must create two symbolic links in it:
+
+* An `images` symbolic link to the top-level `images/` directory
+* A `modules` symbolic link to the top-level `modules/` directory
+
+If the directory that contains an assembly does not have the `images` symbolic link, any images in that assembly or its modules will not be included properly when building the docs.
+
+[TIP]
+====
+To create the symbolic links:
+
+. Navigate to the directory that you need to add the links in.
+. Use the following command to create a symbolic link:
++
+----
+$ ln -s <target_directory> <link_name>
+----
++
+For example, if you are creating the links in a directory that is two levels deep, such as `cli_reference/openshift_cli`, use the following commands:
++
+----
+$ ln -s ../../images/ images
+$ ln -s ../../modules/ modules
+----
++
+Be sure to adjust the number of levels to back up (`../`) depending on how deep your directory is.
+
+If you accidentally create an incorrect link, you can remove that link by using `unlink <link_name>`.
+====
+
 == Assembly/Module titles and section headings
 
 Use sentence case in all titles and section headings. See http://www.titlecase.com/ or https://convertcase.net/ for a conversion tool.
@@ -549,7 +579,10 @@ If a documentation change is due to a Bugzilla bug or Jira issue, the bug/issue
 
 To include a block image (an image on its own line):
 
-1. Put the image file in the symlinked `images` folder.
+1. Put the image file in the `images` folder.
++
+Ensure that the folder containing your assembly contains an `images` symbolic link to the top-level `images/` directory, otherwise the image will not be found when building the docs.
+
 2. In the `.adoc` content, use this format to link to the image:
 +
 ----