Merge pull request #74717 from bergerhoffer/updating-symlink-guidance

Updating symlink and directory creation guidance

Author: bergerhoffer

contributing_to_docs/doc_guidelines.adoc

@@ -9,7 +9,7 @@ link:https://redhat-documentation.github.io/modular-docs/[_Red Hat modular docs
 
 [NOTE]
 ====
-These _Documentation guidelines_ are primarily concerned with the modular structure and AsciiDoc / AsciiBinder requirements for building OpenShift documention. For general style guidelines in OpenShift docs, see the following:
+These _Documentation guidelines_ are primarily concerned with the modular structure and AsciiDoc / AsciiBinder requirements for building OpenShift documentation. For general style guidelines in OpenShift docs, see the following:
 
 * Primary source: link:https://www.ibm.com/docs/en/ibm-style[_IBM Style_]
 * Supplementary source: link:https://redhat-documentation.github.io/supplementary-style-guide/[_Red Hat supplementary style guide for product documentation_]
@@ -207,23 +207,29 @@ Try to shorten the file name as much as possible _without_ abbreviating importan
 
 == Directory names
 
-If you create a directory with a multiple-word name, separate each word with an underscore, for example `backup_and_restore`.
+When creating a new directory, follow these guidelines:
 
-Do not create or rename a top-level directory in the repository and topic map without checking with the docs program manager first.
+* Use underscores to separate multiple-word directory names, for example, `backup_and_restore`.
+* Create the symbolic links for the `images`, `modules`, `snippets` and `_attributes` directories. See xref:symbolic-links[Symbolic links] for instructions.
+* Use the CLI (`mkdir <directory_name>`) instead of an editor, to avoid potential syncing issues.
+* Do not copy another directory or its symbolic links when creating the new directory, to avoid issues with the symbolic links.
+* Do not create or rename a top-level directory in the repository and topic map without checking with the docs program manager first. If a book is being created or modified, there are changes on the Customer Portal that must also be made.
 
-Avoid creating two levels of subdirectories because the link:https://github.com/openshift/openshift-docs/issues/52149[breadcrumb bar on docs.openshift.com breaks]. If you have a valid use case for two levels of subdirectories, talk with your DPM/CS (and, for aligned teams, the OpenShift DPM) for approval before creating it.
+[[symbolic-links]]
+=== Symbolic links
 
-When creating a new directory or subdirectory, you must create four symbolic links in it:
+When creating a new directory or subdirectory, you must create these four symbolic links in it:
 
 * An `images` symbolic link to the top-level `images/` directory
 * A `modules` symbolic link to the top-level `modules/` directory
 * A `snippets` symbolic link to the top-level `snippets/` directory
 * An `_attributes` symbolic link to the top-level `_attributes/` 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]
+[IMPORTANT]
 ====
+If these symbolic links aren't included in an assembly's directory, any images in that assembly or its modules are not included properly when building the docs.
+====
+
 To create the symbolic links:
 
 . Navigate to the directory that you need to add the links in.
@@ -236,16 +242,21 @@ $ 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
-$ ln -s ../../snippets/ snippets
-$ ln -s ../../_attributes/ _attributes
+[openshift-docs ~]$ cd cli_reference/openshift_cli
+[openshift_cli ~]$ ln -s ../../images/ images
+[openshift_cli ~]$ ln -s ../../modules/ modules
+[openshift_cli ~]$ ln -s ../../snippets/ snippets
+[openshift_cli ~]$ ln -s ../../_attributes/ _attributes
 ----
 +
 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>`.
-====
+If you accidentally create an incorrect symbolic link, you can remove that link by using `unlink <link_name>`. For example, the following commands unlink an incorrect `images` symbolic link in the `cli_reference/openshift_cli` directory:
+
+----
+[openshift-docs ~]$ cd cli_reference/openshift_cli
+[openshift_cli ~]$ unlink images
+----
 
 == Assembly/Module titles and section headings