From ce9dd60254d06ac11fa3ffc9ad1fb55e16c8d308 Mon Sep 17 00:00:00 2001 From: daobrien Date: Tue, 20 Dec 2022 00:22:35 +1000 Subject: [PATCH 1/2] Working on #450. --- en-US/A.xml | 18 ++++++++---------- en-US/Author_Group.xml | 2 +- en-US/B.xml | 5 ++--- en-US/Book_Design.xml | 6 ++++-- en-US/Cross_references.xml | 2 +- 5 files changed, 16 insertions(+), 17 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index 48c5460..52368b4 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -5,9 +5,7 @@ ]> A - - "&" and "+" @@ -55,10 +53,10 @@ all-in-one - allinone - n., adj. Hyphenate in both places. Do not use "allinone" or other variations. + n., adj. Write as shown as both a noun and an adjective. + Do not use other variations. @@ -78,7 +76,7 @@ - + alternative @@ -98,7 +96,7 @@ For times of day, use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". - + See also . @@ -123,7 +121,7 @@ The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . - + For more information about Intel® trademarks, see and . @@ -157,9 +155,9 @@ - + - + diff --git a/en-US/Author_Group.xml b/en-US/Author_Group.xml index ab048b7..0c30a92 100644 --- a/en-US/Author_Group.xml +++ b/en-US/Author_Group.xml @@ -5,7 +5,7 @@ ]> - Red Hat Documentation Team + Red Hat Documentation Team diff --git a/en-US/B.xml b/en-US/B.xml index ebfca95..31cf889 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -75,7 +75,6 @@ Do not use. Instead, use "compatible with earlier versions" to refer to something that is compatible with older equipment or previous versions of software. See also . - @@ -362,8 +361,8 @@ broadcast - To send the same message simultaneously to multiple recipients. Broadcasting is a useful feature in email systems. - diff --git a/en-US/Book_Design.xml b/en-US/Book_Design.xml index 636518f..ca49a26 100644 --- a/en-US/Book_Design.xml +++ b/en-US/Book_Design.xml @@ -99,7 +99,9 @@ Drawing these basics together might produce the following example abstract: - "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API. The guide explains each API method and demonstrates examples of data models for input and output. This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." + "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API. + The guide explains each API method and demonstrates examples of data models for input and output. + This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." Update or modify each component according to the type of book that you are writing. @@ -122,7 +124,7 @@
Unused Heading Titles - + This section lists various heading titles that might be used in Red Hat technical documentation, but that should be avoided except in specific circumstances. diff --git a/en-US/Cross_references.xml b/en-US/Cross_references.xml index 546c632..5468451 100644 --- a/en-US/Cross_references.xml +++ b/en-US/Cross_references.xml @@ -45,7 +45,7 @@ Must the information be repeated? - This is a hard question, and one that many authors abhor. Often the answer is yes. If the information is vital, and must appear in multiple places, then it must be repeated. It's not a crime. In some circumstances, such is in online help, the reader wants the answer immediately. Do not force even one extra click on them. In a safety situation, it might be the only chance for the reader to find critical information quickly. Any vital information, which is not more than a couple of paragraphs (or half a page, or five rows of a table), can be repeated rather than be cross-referenced to. + This is a hard question, and one that many authors abhor. Often the answer is yes. If the information is vital, and must appear in multiple places, then it must be repeated. In some circumstances, such is in online help, the reader wants the answer immediately. Do not force even one extra click on them. In a safety situation, it might be the only chance for the reader to find critical information quickly. Any vital information, which is not more than a couple of paragraphs (or half a page, or five rows of a table), can be repeated rather than be cross-referenced to. Cross-referencing is a good servant but a poor master. Content still rules! From c00a40efff510df53ee33021023ed301b29422b7 Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 23 Jan 2023 17:08:45 +1000 Subject: [PATCH 2/2] Run Vale over Design.xml. This is the end of part 1/4 of "Run Vale over the style guide." Too big a job to try to handle in one issue and PR. --- en-US/Design.xml | 63 +++++++++++++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 25 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 297d79f..7bb1591 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -16,7 +16,7 @@ Capitalization The standard for all Red Hat technical documentation is title case for all headings and titles. - Table headings, procedure headings, and formal paragraph titles fall under this heading, and consequently, standard title case capitalization rules apply. + Table headings, procedure headings, and formal paragraph titles fall under this heading; standard title case capitalization rules apply. @@ -42,7 +42,7 @@ Be frugal with punctuation. - In most cases, avoid semicolons, colons, dashes, and similar punctuation unless part of the actual subject, or a proper name. + Avoid semicolons, colons, dashes, and similar punctuation unless part of the actual subject, or a proper name. Do not use terminating periods. @@ -102,7 +102,7 @@ For example, for a button labeled Save As..., do not include the ellipsis in the documentation. - In most cases, do not include the element type in instructions. + Avoid including the element type in instructions. For example, rather than "Click the Save button", write "Click Save". @@ -136,7 +136,7 @@
Navigating Through Multiple UI Options - Use "Navigate to" when moving through multiple UI options because it covers all cases where you might have to click, point to, press, select, or otherwise make a series of selections to initiate an action. + Use "Navigate to" when moving through multiple UI options because it covers all cases where you might have to click, point to, press, select, or otherwise make a series of selections to start an action. For example, "From the OpenShift web console, navigate to Monitoring → Alerting." @@ -182,7 +182,7 @@ RHEL 8 uses the following approach to starting applications from the desktop. - In an effort to maintain consistency and to make translation easier, Red Hat documentation assumes use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. + To maintain consistency and to make translation easier, Red Hat documentation assumes the use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. The preferred approach is to use the Super key to enter the Activities Overview, to enter the name of the required application, and to press Enter. @@ -272,7 +272,7 @@ Target options [directory] - The optional directory into which the repository will be cloned. + The optional directory into which the repository is cloned. It must be replaced with a valid value, or be omitted. @@ -326,7 +326,8 @@ Target options ([username@]hostname:/directory) - The optional username, indicated by brackets ([]), followed by the hostname and path to the target directory. All aspects of this component must be replaced with valid values. + The optional username, indicated by brackets, [], followed by the hostname and path to the target directory. + All aspects of this component must be replaced with valid values. @@ -336,7 +337,7 @@ - In most cases, avoid using the and options on most commands, especially when logged in as the root user. This can lead to unintended consequences, such as removing files or directories by mistake or installing packages or other software that might not suit your system. Refer to the following examples: + Avoid using the and options on most commands, especially when logged in as the root user. This can lead to unintended consequences, such as removing files or directories by mistake or installing packages or other software that might not suit your system. Refer to the following examples: [root@serverc pam.d]# rm -f system-auth password-auth @@ -353,7 +354,8 @@
Documenting Multiple or Long Commands - Sometimes you need to demonstrate how to use long commands that extend over two or more lines, or that include several commands in a single example. If the commands are relatively short and straightforward, then include the commands on consecutive lines: + Sometimes you need to show how to use long commands that extend over two or more lines, or that include several commands in a single example. + If the commands are relatively short and straightforward, then include the commands on consecutive lines. Documenting Multiple Commands @@ -387,7 +389,7 @@ $ vi myFile.txt Do not mix these styles. - Maintain the same style throughout your document, book, and product set. + Use the same style throughout your document, book, and product set. @@ -410,7 +412,7 @@ $ vi myFile.txt Wrapping Long Commands Without Continuation Characters or PS2 Prompts - This example uses neither continuation characters nor PS2 prompts, but it does demonstrate how to use line indentation to help to clarify long commands. + This example uses neither continuation characters nor PS2 prompts, but it does show how to use line indentation to help to clarify long commands. # cd /var/lib/katello @@ -470,7 +472,7 @@ $ vi myFile.txt 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. + It also refers to temporarily changing the privileges of the current user to perfom those operations without changing user accounts. @@ -587,7 +589,8 @@ $ vi myFile.txt
Using Host and Usernames Correctly - Many examples in Red Hat documentation require the use of usernames, hostnames, IP addresses, and similar information. In an effort to reduce security risks, to minimize translation overhead, and to maintain consistency, Red Hat recommends the following approach. + Many examples in Red Hat documentation require the use of usernames, hostnames, IP addresses, and similar information. + To reduce security risks, to minimize translation overhead, and to maintain consistency, Red Hat recommends the following approach: @@ -598,7 +601,8 @@ $ vi myFile.txt - Use RFC 2606 to determine suitable domain names. For documentation and example purposes, it is typically example.com, example.net, example.org, and example.edu. + Use RFC 2606 to find suitable domain names. + For documentation and example purposes, it is typically example.com, example.net, example.org, and example.edu. @@ -618,7 +622,7 @@ $ vi myFile.txt [root@fedora ~]# setfacl -m u:user1:rw /project/file1 - The following list provides further alternatives: + The following list provides further options: @@ -685,7 +689,8 @@ $ vi myFile.txt - Include a diverse set of names in your examples to reflect the diversity of the real world. For example, use male, female, and culturally diverse names that suggest a variety of backgrounds in examples to avoid implying that only certain groups have specific skills. + Include a diverse set of names in your examples to reflect the diversity of the real world. + For example, use male, female, and culturally diverse names that suggest various backgrounds in examples to avoid implying that only certain groups have specific skills. @@ -1087,14 +1092,18 @@ $ vi myFile.txt - In most cases, major changes take place in major version releases, and are carried through any minor updates to that release. If you are referring to a major change, or to the first appearance of a new technology, it is therefore most accurate to refer to the major release. + Major changes usually take place in major version releases, and are carried through any minor updates to that release. + If you are referring to a major change, or to the first appearance of a new technology, it is therefore most accurate to refer to the major release. - Avoid using the "dot-oh" release number. For example, do not use Red Hat Enterprise Linux 6.0. Use instead Red Hat Enterprise Linux 6. + Avoid using the "dot-oh" release number. + For example, do not use Red Hat Enterprise Linux 6.0. + Use instead Red Hat Enterprise Linux 6. - This rule applies only to Red Hat products. Refer to other companies' products and use their version numbers as they use them. + This rule applies only to Red Hat products. + Refer to other companies' products and use their version numbers as they use them. @@ -1103,14 +1112,17 @@ $ vi myFile.txt
Using Admonitions - To call attention to a statement, use an admonition. Red Hat technical documentation currently uses Note, Important, and Warning admonitions. + To call attention to a statement, use an admonition. + Red Hat technical documentation currently uses Note, Important, and Warning admonitions. - Admonitions automatically include a suitable title according to the type of admonition. Do not use a phrase or anything else for the title. Keep in mind these considerations if using admonitions: + Admonitions automatically include a suitable title according to the type of admonition. + Do not use a phrase or anything else for the title. + Keep the following considerations in mind if using admonitions: - Keep the statements as brief and to the point as possible. + Keep statements brief and to the point. @@ -1122,19 +1134,20 @@ $ vi myFile.txt - Use a Note admonition to bring additional information to the user's attention. + Use a Note admonition to bring extra information to the user's attention. - Use an Important admonition to show the user a piece of information that should not be overlooked. While this information might not change anything that the user is doing, it should show the user that this piece of information could be vital. + Use an Important admonition to show the user a piece of information that should not be overlooked. + This information might not change anything that the user is doing, but it should show the user that this piece of information could be vital. - Use a Warning admonition to alert the reader that the current setup will change or be altered, such as files being removed, and not to perform the operation unless fully aware of the consequences. + Use a Warning admonition to alert the reader to potential changes, such as files being removed, and not to perform the operation unless fully aware of the consequences.