Merge pull request #427 from bburt-rh/issue-235-add-examples-to-root-cli-commands-entry

Issue #235: add some examples to root cli commands entry

Author: mportman12

supplementary_style_guide/style_guidelines/code-commands.adoc

@@ -7,11 +7,12 @@
 
 Some commands require root privileges to run. Users without root privileges must first do one of the following to run such a command:
 
-* Run `su -` to switch to the root user account.
 * Preface the command with `sudo` to temporarily change their current privileges.
+* Run `su -` to switch to the root user account.
 
 Use the following guidelines when you document commands that require root privileges:
 
+* If a command requires a temporary switch to root privileges, use the `sudo` command at the beginning of the sample command syntax rather than the `su -` command.
 * If you include a shell prompt in a sample command, always show the correct prompt for a regular user (`$`) or a user with root privileges (`#`).
 +
 [NOTE]
@@ -20,8 +21,20 @@ Do not rely solely on a shell prompt in a sample command to indicate the require
 If you include a shell prompt to indicate that a user with root privileges must run the command, also include a statement about this requirement in the step text, the introductory text, or the prerequisites.
 ====
 +
-* If a command requires a temporary switch to root privileges, use `sudo` at the beginning of the sample command syntax. If the sample command includes a shell prompt together with `sudo`, the prompt should remain `$` and not be changed to `#`.
-* If multiple commands in a procedure require root privileges, add introductory content to tell the user what to do. For example, "The commands in this procedure require root privileges to run. Either run `su -` to switch to the root user or preface the commands with `sudo`."
+* When a sample command includes `sudo`, use the `$` prompt, not `#`, as shown in the following example: 
++
+[source,terminal]
+----
+$ sudo systemctl start firewalld
+----
++
+* If multiple commands in a procedure require root privileges, add introductory content to tell the user about the requirement. 
+The following example shows one way that you could integrate a requirement for root access into the introduction for a procedure:
++
+.Example AsciiDoc
+----
+Some tasks in this procedure require root privileges, which you can get temporarily by prefixing commands with `sudo`.
+----
 
 .Additional resources
 * link:https://www.redhat.com/sysadmin/difference-between-sudo-su[Exploring the differences between sudo and su commands in Linux]