Merge pull request #32197 from jeana-redhat/path-replacement-values

User-replaced values: added examples showing mutliple words and a file path

Author: jeana-redhat

contributing_to_docs/doc_guidelines.adoc

@@ -21,9 +21,7 @@ In the Atom editor, you can use `Ctrl`+`J` to undo hard wrapping on a paragraph.
 ====
 
 == Assembly file metadata
-
-Every assembly file should contain the following metadata at the top, with no line
-spacing in between, except where noted:
+Every assembly file should contain the following metadata at the top, with no line spacing in between, except where noted:
 
 ----
 [id="<unique-heading-for-assembly>"]                            <1>
@@ -905,9 +903,7 @@ Now using project "my-project" on server "https://openshift.example.com:6443".
 ----
 ....
 
-* To mark up command syntax, use the code block and wrap any replaceable values in
-angle brackets (`<>`) with the required command parameter, using underscores
-(`_`) between words as necessary for legibility. For example:
+* To mark up command syntax, use the code block and wrap any replaceable values in angle brackets (`<>`) with the required command parameter, using underscores (`_`) between words as necessary for legibility. For example:
 +
 ....
 To view a list of objects for the specified object type, enter the following command:
@@ -930,6 +926,33 @@ This renders as:
 +
 NOTE: Avoid using full command syntax inline with sentences.
 
+* When referring to a path to a location that the user has selected or created, treat the part of the path that the user chose as a replaceable value. For example:
++
+....
+Create a secret that contains the certificate and key in the `openshift-config` namespace:
+
+[source,terminal]
+----
+$ oc create secret tls <certificate> --cert=<path_to_certificate>/cert.crt --key=<path_to_key>/cert.key -n openshift-config
+----
+....
++
+This renders as:
++
+--
+> Create a secret that contains the certificate and key in the `openshift-config` namespace:
+>
+> ----
+> $ oc create secret tls <certificate> --cert=<path_to_certificate>/cert.crt --key=<path_to_key>/cert.key -n openshift-config
+> ----
+--
++
+The following example shows a more complex use of user-chosen elements and prescriptive placement:
++
+....
+<resource_group_name>/providers/Microsoft.Compute/diskEncryptionSets/<disk_encryption_set_name>
+....
+
 * If you must provide additional information on what a line of a code block
 represents, use callouts (`<1>`, `<2>`, etc.) to provide that information.
 +
@@ -1663,12 +1686,20 @@ a|
 `<project>`
 
 `<deployment>`
+
+`<install_mode_value>`
 ....
 
 a|
 > Use the following command to roll back a Deployment, specifying the Deployment name:
 >
 > `oc rollback <deployment>`
+>
+> &nbsp;
+>
+> Apply the new configuration file:
+>
+> `oc apply -f <path_to_configuration_file>/<filename>.yaml`
 
 |Use single asterisks for web console / GUI items (menus, buttons, page titles, etc.).
 Use two characters to form the arrow in a series of menu items (`$$->$$`).