diff --git a/en-US/B.xml b/en-US/B.xml index 611afd2..fcbedb5 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -419,8 +419,11 @@ Describe a GUI button as a "button," not a "pushbutton" or "push-button." - Ordinarily you would not include the text "button" in a procedure or description. For example, "Click OK to continue" is perfectly acceptable. It may be necessary to distinguish between buttons and links; for example, "Click the Unload button." + Ordinarily you would not include the text "button" in a procedure or description. For example, "Click OK to continue" is perfectly acceptable. It may be necessary to distinguish between buttons and links; for example, "Click the Download link." + + See also . + diff --git a/en-US/Conventions_for_Writers_and_Editors.xml b/en-US/Conventions_for_Writers_and_Editors.xml index cca3171..3f5dfde 100644 --- a/en-US/Conventions_for_Writers_and_Editors.xml +++ b/en-US/Conventions_for_Writers_and_Editors.xml @@ -27,7 +27,7 @@ Usage Dictionary - The Usage Dictionary provides guidelines for the correct use of common terms in Red Hat documentation, which terms to avoid, and the preferred spelling if variations exist. + The Usage Dictionary provides guidelines for the correct use of common terms in Red Hat documentation, which terms to avoid, and the preferred spelling if variations exist. diff --git a/en-US/Design.xml b/en-US/Design.xml index 59eee63..6620120 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -81,13 +81,42 @@ The following sections highlight exceptions or cases that might otherwise cause confusion.
- GUI Elements and Punctuation + GUI Elements, Punctuation, and Symbols - Do not include punctuation that appears on GUI elements, unless omission of that punctuation might lead to confusion. + When describing GUI elements, do not include punctuation that appears on those elements, unless omission of that punctuation might lead to confusion. For example, for a button labeled Save As..., do not include the ellipsis in the documentation. + + In most cases, do not include the object type in instructions. + For example, rather than "Click the Save button," write "Click Save." + + + In some cases it is preferred practice to include the object type for the sake of clarity. + Consider the following: + + Preferred Style for Documenting Symbols and Other Special Characters + + Click the + sign. + + + Click the ^ symbol. + + + + If you cannot easily reproduce the symbol, include a screen capture and/or a succinct description of the object type. + Use this approach for icons, especially when they have no tooltip or other help text. + + Preferred Style for Documenting Icons + + Click the Upload ( + + + + ) icon to upload the files to the server. + + See the Computer Interfaces chapter in The IBM Style Guide for more information. @@ -310,7 +339,7 @@ $ vi myFile.txt You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required. You can use this option for either of the two designs mentioned above. - + Wrapping Long Commands with Continuation Characters @@ -338,6 +367,7 @@ $ vi myFile.txt
+
Referring to Replaceable Paths @@ -371,6 +401,89 @@ $ vi myFile.txt
+
Using Escalated Privileges Correctly + + + This section is aimed primarily at Red Hat Training course material, but the principles and guidelines apply equally in any environment. + + + + The term escalated privileges refers to changing to a user whose privileges allow operations that a normal user cannot access. + It also refers to temporarily changing the privileges of the current user to perfom those operations without actually changing user accounts. + + Classroom Exceptions + + Although security is important, it is more important to not have unnecessary classroom security distract from the immediate topic being taught. + + +
General Recommendations + + + These are recommendations, not rules. + As with most things, consistency is important. + Do not swap between different approaches without reason. + Choose which approach works best for your situation and use it consistently. + + + + + + In all cases, use the minimum privilege level required to achieve the task. + + + + + In exercises, use sudo and sudo -i and set this up to work throughout all relevant systems in the classroom. + Do not use su - without good cause. + + + + + When there is a scattered minority of privileged commands in a mostly unprivileged exercise, use sudo on a per-command basis. + + + + + When the exercise is majority privileged, or has a significant number of privileged commands, use sudo -i either at the beginning of the exercise, or at an appropriate step where the privileged commands begin. + + + + + In the narrative, do not show the use of su or sudo, but always show privileged commands with the correct prompt. + See for information about command prompts. + + + +
+
Exceptions + + Some courses are specifically designed to teach sudo and its variations, the use of the related files, such as /etc/sudoers and so on. + For these courses, use the required variation for the topic being taught. + +
Ansible Courses + + + + Ansible courses typically use a devops user with passwordless sudo access (devops ALL=(ALL) NOPASSWD: ALL) on managed nodes to enable the use of become without a become password as root to do anything. + + + + + As much as possible, leave the system-wide default as become: false or become: no and if a single task needs privileges, set become: true or become: yes on that task. + + + + + If most tasks in a play require escalated privileges, set the entire play to become: true or become: yes and possibly selectively set individual tasks to become: false or become: no. + + + +
+
+ + +
+
Describing How to View and Edit Files diff --git a/en-US/L.xml b/en-US/L.xml index e319a43..1e2e109 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -100,9 +100,6 @@ adj. Hyphenate. - - See The IBM Style Guide for more information. - diff --git a/en-US/images/reload.png b/en-US/images/reload.png new file mode 100644 index 0000000..e341c10 Binary files /dev/null and b/en-US/images/reload.png differ