Merge pull request 'Issue #210 - Add Fedora Server style conventions to help guide contribution and to track decisions made by the Fedora Server SIG/WG' (!202) from goroboro/user-documentation:ISSUE210-style into main

Reviewed-on: #202

README.md

@@ -11,6 +11,8 @@ Fork this repository, so you are not pushing updates directly into the main bran
 Start adding the actual AsciiDoc content. While writing, make sure your new source files are included in the nav.adoc configuration file of the module you are using (./modules/ROOT/ ). 
 Also make sure to use local preview often to check your markup.
 
+Please see our [Style Guidelines](STYLE.md) to help guide your content.
+
 Once you finish, commit your changes and push them to your fork.
 
 Use forge to make a pull request from your fork to the repository’s main branch.

STYLE.md

@@ -0,0 +1,75 @@
+# Documentation Style Guidelines
+
+Fedora Server documentation follows the style guidelines defined at https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/style-guide/
+
+Additionally the following general style decisions have been agreed for Fedora Server documentation:
+
+## File Edit Instructions
+
+In general, avoid mentioning the editor or including the editor in a codeblock. Describe the filepath in the text preceding the file content and then
+include the file content in a codeblock. For example:
+
+``` 
+ Create or edit the file at /path/to/file using your preferred editor running under sudo to obtain elevated privileges. The file content should match:
+ [source,ini]
+ ----
+ [main]
+ key=<value>
+ ----
+```
+
+Use of HEREDOC is permitted, but is only preferred for very small file creation actions. We want to encourage users to actually review the content that they enter into an editor when creating and editing files. An example of a small HEREDOC file creation might be:
+
+```
+[source,console]
+----
+$ sudo tee /etc/sysctl.d/50-enable-forwarding.conf << 'EOF'
+net.ipv4.ip_forward=1
+net.ipv6.conf.all.forwarding=1
+EOF
+----
+```
+
+TIP: By quoting the 'EOF' in the command, you can often avoid bash variable expansion if the file contains variable strings. Read more on HEREDOC at [The Linux Documentation Project](https://tldp.org/LDP/abs/html/here-docs.html).
+
+## Codeblocks and Command Syntax
+
+Codeblock class directives for shell interactions should use the `[source,console]` classes. This helps to handle the exclusion of the shell prompt in a copy action, and provides some shell syntax highlighting. 
+
+Although Asciidoc supports a variety of codeblock delimiters, we always use `----` to indicate the start and the end of a block.
+
+For variable substitution use `<variable_name>` in the codeblock and then preferably call out the variable in surrounding text to explain what it should be substituted with.
+
+In addition to the standard style instruction to use a shell prompt ($ or #) to indicate privilege level and set the input apart from output. We prefer that commands are generally run with user privileges and
+ sudo to obtain root privileges where required. The majority of your shell commands should be preceded with a $, unless there is a significant reason that something explicitly runs as root. For example:
+
+
+``` 
+ [source,console]
+ ----
+ $ sudo some_command --opt <my_var>  
+ Output from some_command run with root privileges, if valuable to show.
+ $ some_command
+ Output from some_command run as a standard user, if valuable to show.
+ # some_command 
+ Output from some_command run as root - avoid doing this, if possible.
+ ----
+```
+
+It is worth noting that simply putting sudo in front of a command that was previously run as root might not give the behavior you expected, particularly if the command included pipes or redirects. For example:
+
+```
+# echo 1 > /proc/sys/net/ipv4/ip_forward
+```
+ 
+is *not* the same as:
+
+```
+$ sudo echo 1 > /proc/sys/net/ipv4/ip_forward
+```
+
+The redirect will run as the standard user and only the echo will run under sudo. Instead, run the echo as the standard user and pipe the output to tee running under sudo:
+
+```
+$ echo 1 | sudo tee /proc/sys/net/ipv4/ip_forward
+```