From b0e448da34bb26868a81eea070226041379658a6 Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 1 Feb 2021 08:58:14 +1000 Subject: [PATCH 1/8] Changed entity for non-breaking space to hex version. For some reason the original version ( ) stopped working in this, and only this, instance. --- en-US/Conventions_for_Writers_and_Editors.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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. From 204cdba2cf27375971b68a7dacd9b262c64ccd45 Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 1 Feb 2021 11:34:12 +1000 Subject: [PATCH 2/8] Addresses #220 Document how to click symbols. Includes examples and also how to use inline images for icons. --- en-US/Design.xml | 35 ++++++++++++++++++++++++++++++++--- en-US/images/reload.png | Bin 0 -> 547 bytes 2 files changed, 32 insertions(+), 3 deletions(-) create mode 100644 en-US/images/reload.png diff --git a/en-US/Design.xml b/en-US/Design.xml index 59eee63..d0d91bc 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 diff --git a/en-US/images/reload.png b/en-US/images/reload.png new file mode 100644 index 0000000000000000000000000000000000000000..e341c10bb123e675660d17fedb55cf5cdb88d9d0 GIT binary patch literal 547 zcmV+;0^I$HP)Vl&|00004b3#c}2nYxW zdZgXgFbngSdJ^%m!E_6j$bVG7w zVRUJ4ZXi@?ZDjyWZ*CwkF(5`|VjwawGBF@AFgh_bIy5;TK}{e*MN?FCWw;jr00DbR zL_t(YiS3s$PlG@hhTkJ>2wVx&#CN&C_ucord>og9Y(BqYaEjwNGqxo{NM-~8IS+0d%Gb^tk-7lqO(Yz- zOE7N$0Hm(LyaA~Xa3ZNXWk=z@?_+u~6`n6wr~C%KOs{A5tZ@yYC(na@e<{>~#_&9N z8v~8tWne`a2pOmi=fR3Hz+`fs#_TH_nx-{2P#b=K_mF};&xNk*X>3S`@D^@rAP53P z(Yigjw{T$^20YKj0S8V*Db3`l>V9R-+MgPw6z;;^I)~Ta-QoV>qAFc*jD-LIRo$z# za*Gs2Yedl-0Khbj`tb4b7yw{d7EaGjgy2t)OE``L0C;(Qt`D!0d1w|EY@*$K=ZQkb z;M_Vw#Y4u#;HF`Kg&|gqVO3G2N=Ktn;r-IK&u`|XlbV9 Date: Mon, 1 Feb 2021 11:42:20 +1000 Subject: [PATCH 3/8] Addresses #224 Update entry for life cycle. Remove reference to IBM guide because it conflicts with our own. Note that this version does not build because of an entity issue, but that's been fixed as part of a separate commit. --- en-US/L.xml | 3 --- 1 file changed, 3 deletions(-) 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. - From af74d4059c9d9e15d73da6ce22bcfeb92676625d Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 1 Feb 2021 12:45:35 +1000 Subject: [PATCH 4/8] Addresses #219 Update entry for "Button" Changed example text and added link to "Documenting the UI." Note that this doesn't build due to an entity issue but that's been fixed in another commit. --- en-US/B.xml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) 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 . + From 24ca3c81482c0612d9960622785e5d489adf34d6 Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 1 Feb 2021 12:50:38 +1000 Subject: [PATCH 5/8] Addresses #219 Update entry for "Button." Update example text and add link to Documenting the UI. --- en-US/B.xml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) 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 . + From db13a3f0c172df10cd341ececd07c5754778e9f1 Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 1 Feb 2021 13:48:20 +1000 Subject: [PATCH 6/8] Fix missing closing quote. --- en-US/Design.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index d0d91bc..69ea0b3 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -90,7 +90,7 @@ In most cases, do not include the object type in instructions. - For example, rather than "Click the Save button," write "Click Save. + 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. From c49234b5a846853ff07ec6994417fd0a2a387302 Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 1 Feb 2021 15:08:36 +1000 Subject: [PATCH 7/8] Addresses #222 Recommendations for using sudo. --- en-US/Design.xml | 86 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 85 insertions(+), 1 deletion(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 59eee63..dff5eaf 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -310,7 +310,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 +338,7 @@ $ vi myFile.txt
+
Referring to Replaceable Paths @@ -371,6 +372,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 ALL=ALL(ALL) access 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 From 1f39904068013d3f0818afc493c005081dc527d8 Mon Sep 17 00:00:00 2001 From: David O'Brien Date: Mon, 1 Feb 2021 23:03:55 +1000 Subject: [PATCH 8/8] Update en-US/Design.xml Co-authored-by: mweetman-redhat --- en-US/Design.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index dff5eaf..9893766 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -435,7 +435,7 @@ $ vi myFile.txt - Ansible courses typically use a devops user with passwordless sudo ALL=ALL(ALL) access on managed nodes to enable the use of become without a become password as root to do anything. + 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.