From 375240871d986ee3892147ceba8d0815c48d3ff1 Mon Sep 17 00:00:00 2001 From: daobrien Date: Wed, 3 Nov 2021 20:49:57 +1000 Subject: [PATCH 01/30] Mostly clean-up to deal with book title changes, etc. --- en-US/Book_Info.xml | 2 +- en-US/Conventions_for_Writers_and_Editors.ent | 5 -- en-US/Conventions_for_Writers_and_Editors.xml | 65 ------------------- en-US/Revision_History.xml | 2 +- ...le_Conventions_for_Writers_and_Editors.xml | 13 +++- 5 files changed, 13 insertions(+), 74 deletions(-) delete mode 100644 en-US/Conventions_for_Writers_and_Editors.ent delete mode 100644 en-US/Conventions_for_Writers_and_Editors.xml diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index f3ceb25..06528e6 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -1,6 +1,6 @@ + %BOOK_ENTITIES; ]> diff --git a/en-US/Conventions_for_Writers_and_Editors.ent b/en-US/Conventions_for_Writers_and_Editors.ent deleted file mode 100644 index 87f791a..0000000 --- a/en-US/Conventions_for_Writers_and_Editors.ent +++ /dev/null @@ -1,5 +0,0 @@ - - - - - \ No newline at end of file diff --git a/en-US/Conventions_for_Writers_and_Editors.xml b/en-US/Conventions_for_Writers_and_Editors.xml deleted file mode 100644 index d8ebb90..0000000 --- a/en-US/Conventions_for_Writers_and_Editors.xml +++ /dev/null @@ -1,65 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - - - Writing Style Guide - - - Recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases. - - - - - - - - - - - - - - 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. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml index 92f53f6..a02e99a 100644 --- a/en-US/Revision_History.xml +++ b/en-US/Revision_History.xml @@ -1,6 +1,6 @@ + %BOOK_ENTITIES; ]> diff --git a/en-US/Style_Conventions_for_Writers_and_Editors.xml b/en-US/Style_Conventions_for_Writers_and_Editors.xml index d8ebb90..012de66 100644 --- a/en-US/Style_Conventions_for_Writers_and_Editors.xml +++ b/en-US/Style_Conventions_for_Writers_and_Editors.xml @@ -1,6 +1,6 @@ + %BOOK_ENTITIES; ]> @@ -59,7 +59,16 @@ - + + Revision History + + + Make the release notes for the style guide available on stylepedia.net: + + + + + From 5b194c104921ef804411758856a1488149966455 Mon Sep 17 00:00:00 2001 From: alex Date: Mon, 15 Nov 2021 11:25:34 +0100 Subject: [PATCH 02/30] Add entry for on(-, )premise(,s) Closes #289 --- en-US/O.xml | 49 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/en-US/O.xml b/en-US/O.xml index f780786..3fcecf6 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -108,7 +108,54 @@ - + + + + on premise + + + adverb Write as shown. + If an adjective before a noun, use "on-premise." + Do not use "on premises". + + + + + + + + on-premise + + + adjective Write as shown. + Use as an adjective before a noun, otherwise use "on premise." + Do not use "on-premises." + + + + + + + on premises + + + Do not use, use "on premise." + + + + + + + + on-premises + + + Do not use, use "on premise." + + + + + From e9f52a57564b209c17482fbfbbaed512e7b53b91 Mon Sep 17 00:00:00 2001 From: alex Date: Mon, 15 Nov 2021 11:25:34 +0100 Subject: [PATCH 03/30] Fix small issues --- en-US/O.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/en-US/O.xml b/en-US/O.xml index 3fcecf6..ed2c28e 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -115,8 +115,8 @@ adverb Write as shown. - If an adjective before a noun, use "on-premise." - Do not use "on premises". + If an adjective before a noun, use "." + Do not use "." @@ -128,8 +128,8 @@ adjective Write as shown. - Use as an adjective before a noun, otherwise use "on premise." - Do not use "on-premises." + Use as an adjective before a noun, otherwise use "." + Do not use "." @@ -139,7 +139,7 @@ on premises - Do not use, use "on premise." + Do not use, use "." @@ -150,7 +150,7 @@ on-premises - Do not use, use "on premise." + Do not use, use "." From f8ca7a289d4725a569df14b082e115188fcf0c35 Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 15 Nov 2021 21:57:56 +1000 Subject: [PATCH 04/30] A bit of clean up to Alex's PR. --- en-US/O.xml | 36 ++++++++++-------------------------- 1 file changed, 10 insertions(+), 26 deletions(-) diff --git a/en-US/O.xml b/en-US/O.xml index ed2c28e..b0a021f 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -114,48 +114,32 @@ on premise - adverb Write as shown. - If an adjective before a noun, use "." - Do not use "." + adverb + Two words. + + + adj. + Hyphenate if used as an adjective before a noun. + Otherwise, use the two-word form. - - on-premise - - - adjective Write as shown. - Use as an adjective before a noun, otherwise use "." - Do not use "." - - - - - on premises + on premises, on-premises - Do not use, use "." + Do not use. + See . - - on-premises - - - Do not use, use "." - - - - - From 3bd8e34fa740dd703cecb0af8cb792564490ee8e Mon Sep 17 00:00:00 2001 From: daobrien Date: Wed, 24 Nov 2021 21:40:22 +1000 Subject: [PATCH 05/30] Fixes #294 Remove entry for "check box" (no longer correct and covered in IBM) and update to other references that use "check box". --- en-US/C.xml | 9 --------- en-US/U.xml | 4 ++-- 2 files changed, 2 insertions(+), 11 deletions(-) diff --git a/en-US/C.xml b/en-US/C.xml index 59b63a9..2e349e4 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -111,16 +111,7 @@ - - check box - - - n. Two words. Do not use "checkbox" or "check-box." - - - - chipset diff --git a/en-US/U.xml b/en-US/U.xml index 5a8c1be..12bfe6d 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -69,10 +69,10 @@ unset - Incorrect. Use "Clear" instead, to refer to removing a selection from a check box. + Incorrect. Use "Clear" instead, to refer to removing a selection from a checkbox. - To disable the Wobbly Widget application, clear the Enable Wobbly Widget check box. + To disable the Wobbly Widget application, clear the Enable Wobbly Widget checkbox. This rule matches only TCP packets where the SYN flag is set and the ACK flag is cleared. From 9f7bf26585cb438d59ab0a97eb820017898596c2 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Thu, 9 Dec 2021 12:33:31 +0000 Subject: [PATCH 06/30] #285 Minor punctuation fix (#314) Co-authored-by: Julian Cable --- en-US/Grammar.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 2a305c6..a3389ef 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -420,7 +420,7 @@ "That" in Clauses - Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English, + Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English. From b97b7e20714556b71ca5d66579ef6e3d894a9d94 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Thu, 16 Dec 2021 13:45:19 +0000 Subject: [PATCH 07/30] Bogus change to test commits. (#320) * Bogus change to test commits. * Resolved space. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 32e572a..f07ab67 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ WritingStyleGuide A guide to writing clear, concise, and consistent technical documentation. -The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat. +The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat. It covers recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases. From 743b9fae628c2fb384b4897982f9de05e9cfb417 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Tue, 21 Dec 2021 16:40:29 +0000 Subject: [PATCH 08/30] #291 Diagram labels as sentence case only. (#321) --- en-US/Design.xml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 08003e2..200b473 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -16,10 +16,9 @@ Capitalization The standard for all Red Hat technical documentation is title case for all headings and titles. - Diagram labels, table headings, procedure, and formal paragraph titles all fall under this heading, and consequently, standard title case capitalization rules apply. + Table headings, procedure headings, and formal paragraph titles fall under this heading, and consequently, standard title case capitalization rules apply. The currently accepted reference for determining title case is at https://titlecase.com/titlecase. - Use sentence case for captions, legends, diagram labels, and table column headers. From 64007b8a896c282e35a95627b02b61a147d8ced1 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 5 Jan 2022 11:30:07 +0000 Subject: [PATCH 09/30] #288 Added guidance about referring to object names. (#329) --- en-US/Design.xml | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 200b473..666196c 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -673,7 +673,41 @@ $ vi myFile.txt - +
+ Referring to Object Names + + Do not use object names as part of normative grammar. A sentence should be complete without the object name. + + + + + + + + + + Example + Improvement + + + + + + + Find the current default StorageClass. + Either: Find the current default storage class. Or: Find the current default StorageClass value. + + + + + + + +
+ +
+ +
Documenting Currencies From 69b5e3ae00dcb8f9d039599700a990e98385a916 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 5 Jan 2022 11:42:45 +0000 Subject: [PATCH 10/30] #318 Commented out section about gerunds and imperatives in titles. (#328) --- en-US/Design.xml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 666196c..856c926 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -41,12 +41,13 @@ Do not use terminating periods. + + See the IBM Style Guide for more information. @@ -56,11 +57,11 @@ Gerunds should be avoided elsewhere. See . - + --> File Names, Commands, and Related Terms - When creating chapter and section titles, do not include file, command, or similar names, and do not include DocBook elements. + When creating chapter and section titles, do not include file, command, or similar names, and do not include markup elements. Instead, focus on the task at hand and introduce the required file and command names in the text. Including such objects in titles is generally considered poor technical writing practice. Depending on how your documentation is built and delivered, including these object types can result in unpredictable results and can even cause failed builds. From 355fd2ffc745bb0fcc8a1fbc8aae27cdc0e1f6bb Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 5 Jan 2022 11:43:27 +0000 Subject: [PATCH 11/30] 293 Resolved a bug with referring to punctuation marks. (#327) --- en-US/Punctuation.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index e1046c9..984414c 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -497,7 +497,7 @@ Deleted paragraph now that DocBook tagging no longer applies. --> To refer to a punctuation mark or special character, use its name alone if it is one of the following standard characters: - . , : ; ' " ( ) [ ] ! ? + . , : ; ' " ( ) [ ] { } ! ? For another character, use its name followed by the symbol in parentheses. @@ -511,7 +511,7 @@ Deleted paragraph now that DocBook tagging no longer applies. --> Use a semicolon to separate two parts of a sentence that can each stand on their own. - The path contains the library qualifier in braces, { }. + The path contains the library qualifier in braces. From 29675e2305aedb1750e3a67c69785ea7628dd372 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 5 Jan 2022 11:44:04 +0000 Subject: [PATCH 12/30] #306 Added guidance about pronouncing file or directory names that begin with special characters. (#326) --- en-US/Design.xml | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 856c926..14d116f 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -723,7 +723,7 @@ $ vi myFile.txt
- Using Abbreviations, Acronyms, and Initialisms Correctly + Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly This section describes how to use abbreviations, acronyms, and initialisms correctly in Red Hat documentation. @@ -762,7 +762,7 @@ $ vi myFile.txt Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see the IBM Style Guide or another suitable reference if you are unsure. - + Initialisms An initialism is an abbreviation that consists of the first letters of words in a phrase, syllables, or some combination thereof. Each character is pronounced separately. For example, FTP is an initialism for File Transfer Protocol. @@ -772,6 +772,24 @@ $ vi myFile.txt Consider pronunciation when using articles. See for more information. + + Special Characters + + Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article. + + + + + If a file or directory name begins with a special character, such as an underscore, then you need to pronounce that character. + + + + For example, using "an _build/ directory" is correct, because you pronounce "an underscore build directory". + + + + Using "a -compile/ directory" is correct, because you pronounce "a dash compile directory". +
From be6318130622111e2ff0ff49bf073d3028cf57c3 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 5 Jan 2022 11:47:13 +0000 Subject: [PATCH 13/30] #310 Anthropomorphism: Avoid 'allow'. (#324) --- en-US/Language.xml | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/en-US/Language.xml b/en-US/Language.xml index 6a76d1d..6d9966a 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -867,6 +867,40 @@ + + + Avoid stating that a product or feature allows the user to do something. Focus instead on what the user does. + + + + + + + + + Example + Improvement + + + + + + + Using the ausearch command allows administrators to focus on only the messages they are interested in. + Administrators can use the ausearch command to focus on only messages of interest. + + + + Collections allow updates to the core Ansible code to be separated from updates to modules and plug-ins. + You can use collections to separate core Ansible code updates from updates to modules and plug-ins. + + + + + + + +
Report an issue From 98ca4b6ce2f076f8b3f0bdae89f12b8649e1c18b Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 5 Jan 2022 11:48:00 +0000 Subject: [PATCH 14/30] #312 Add subsection about consecutive headings. (#323) --- en-US/Book_Design.xml | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/en-US/Book_Design.xml b/en-US/Book_Design.xml index d182a6d..77196bb 100644 --- a/en-US/Book_Design.xml +++ b/en-US/Book_Design.xml @@ -112,11 +112,18 @@ The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory (TM) tools, that Red Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to $productname" near the beginning of the book to introduce the reader to the product. Do not use "Introduction" to introduce the book; that is the task of the Abstract. A further benefit of this usage is that the same introduction can be used across various books to introduce the same product. +
+
+ Placement of Headings + + Do not include two consecutive headings without intervening text. Each heading must be followed by one or more paragraphs of text. If it is difficult to provide meaningful intervening text, then consider whether one of the headings is unnecessary. + +
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. + + This section lists various heading titles that might be used in Red Hat technical documentation, but that should be avoided except in specific circumstances. Overview From bcd5306e2c77c7bb2106a2de4e106aaeaffa2e7e Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 5 Jan 2022 11:48:33 +0000 Subject: [PATCH 15/30] #308 Add 'prebaked' to slang examples. (#322) --- en-US/Language.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Language.xml b/en-US/Language.xml index 6d9966a..d06ea00 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -557,7 +557,7 @@ - pre-baked + pre-baked, prebaked Means "prepared beforehand." Choose a suitable alternative, such as "preconfigured," depending on the context. From 6d7d18da5c9c24c488d78285ae2704ac83aded0a Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 5 Jan 2022 11:52:03 +0000 Subject: [PATCH 16/30] #313 Updated guidance for non-breaking spaces, in a new section. (#325) --- en-US/Design.xml | 81 ++++++++++++++++++++++++++++-------------------- 1 file changed, 48 insertions(+), 33 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 14d116f..f630660 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -824,62 +824,77 @@ $ vi myFile.txt - Use non-breaking spaces to avoid breaking the company name, or product names and their versions, over multiple lines. For example, use a non-breaking space between "Red" and "Hat," and also between "Enterprise," "Linux," and the version number. - - - If you are working with images or other objects where space is especially tight, this rule is more flexible, but "Red Hat" should never be broken over two lines. + Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was..." + + + In this case, "Platform" is part of the product name. In other cases, words like "platform," "manager," and so on might not be part of the product name, in which case an article is acceptable, if not necessary. + + + - Do not use non-breaking spaces between "Red Hat" and any product name. Consider the following DocBook XML examples: + Do not hyphenate or break a product name across lines, as in the following incorrect example: + + Open + -Shift + + + + +
+
+ Using Non-breaking Spaces + + Use a non-breaking space in the following situations to avoid a break across lines: + - Standardize on Red&nbsp;Hat Enterprise&nbsp;Linux. + In the company name, between "Red" and "Hat". - The latest version is Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;8.0 + In a product name, between the last word and a version number. - - For other markup languages, use the equivalent non-breaking space character. - - - - - Do not use non-breaking spaces between extended components of Red Hat product names. For example, "Red Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between "Linux" and "OpenStack", nor between "OpenStack" and "Platform." - - - - - - Do not use non-breaking spaces with other companies' product names. - + + Examples (for AsciiDoc): + + + + + Red{nbsp}Hat Enterprise Linux{nbsp}8 + - - - - Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was..." - - - - In this case, "Platform" is part of the product name. In other cases, words like "platform," "manager," and so on might not be part of the product name, in which case an article is acceptable, if not necessary. - + + + + Red{nbsp}Hat OpenShift Container Platform{nbsp}4.9 + - + - + - + + If you are working with images or other objects where space is especially tight, this rule is more flexible, but "Red Hat" should never be broken over two lines. + + + Non-breaking spaces are not needed elsewhere in a product name and might cause undesirable line-breaking behavior. + In particular, do not use non-breaking spaces between extended components of Red Hat product names. For example, "Red Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between any of the words after "Red Hat". + + + Do not use non-breaking spaces with other companies' product names. +
From e4d913cce05f0d2018450980b434a47f80b66256 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 5 Jan 2022 14:48:29 +0000 Subject: [PATCH 17/30] #299 Add IaC entry (#331) --- en-US/I.xml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/en-US/I.xml b/en-US/I.xml index fabe045..484aca1 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -25,6 +25,17 @@ + + + infrastructure as code (IaC) + + + Based on search volume, the nonhyphenated full term and camel-case acronym are preferred. Use lowercase except in headings or at the start of a sentence. + + + + + - IBM Z From a4367b39bab85f21aead990f991ebbb48b5c71ff Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Thu, 6 Jan 2022 14:48:43 +0000 Subject: [PATCH 18/30] #303 Added allowed use of 'unset' (#334) --- en-US/U.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/U.xml b/en-US/U.xml index 12bfe6d..76b94be 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -69,7 +69,7 @@ unset - Incorrect. Use "Clear" instead, to refer to removing a selection from a checkbox. + Use only to refer to deleting a variable. To refer instead to removing a selection from a checkbox, use "clear". To disable the Wobbly Widget application, clear the Enable Wobbly Widget checkbox. From 3aa4f6508819b7afeaf5fe028b55bbff9886dba1 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Tue, 11 Jan 2022 11:56:00 +0000 Subject: [PATCH 19/30] Jcable/297 Change of standard for punctuation with quotation marks. (#315) * #285 Minor punctuation fix * #297 Change of standard for punctuation with quotation marks. * Further changes to Punctuation chapter Co-authored-by: Julian Cable --- en-US/Punctuation.xml | 37 +++++++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 984414c..7b70a67 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -426,19 +426,44 @@
Quotation Marks + - + + Julius Caesar said, “I came. I saw. I conquered.” + + + +
+ diff --git a/en-US/Design.xml b/en-US/Design.xml index f630660..9db34dc 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -83,15 +83,15 @@ The following sections highlight exceptions or cases that might otherwise cause confusion.
- GUI Elements, Punctuation, and Symbols + User Interface (UI) Elements, Punctuation, and Symbols - When describing GUI elements, do not include punctuation that appears on those elements, unless omission of that punctuation might lead to confusion. + When describing UI 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. + In most cases, do not include the element type in instructions. For example, rather than "Click the Save button," write "Click Save." @@ -123,9 +123,9 @@ See the UI elements chapter in the IBM Style Guide for more information.
- Navigating Through Multiple GUI Options + Navigating Through Multiple UI Options - Use "Navigate to" when moving through multiple GUI 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 initiate an action. For example, "From the OpenShift web console, navigate to Monitoring → Alerting." diff --git a/en-US/E.xml b/en-US/E.xml index 01cafdf..fa64967 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -100,7 +100,7 @@ n. Initialism for "end of line" - Always use uppercase for the initialism. Do not capitalize the expansion except at the beginning of a sentence. When documenting GUI objects, use the same capitalization as shown in the GUI. + Always use uppercase for the initialism. Do not capitalize the expansion except at the beginning of a sentence. When documenting UI objects, use the same capitalization as shown in the UI. diff --git a/en-US/Language.xml b/en-US/Language.xml index d06ea00..31bb084 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1189,7 +1189,7 @@ Numbers (move from N entry) --> Sometimes multiple terms have a single meaning. If terms are used inconsistently, users (and translators) will assume they refer to different things. It is best to use a single term for a single concept throughout. - For example, "Administration GUI" and "Administration Console" could both be used to refer to a single application or to different applications. For this reason it is important that writers choose the most suitable term for each situation and use it consistently. + For example, "Administration UI" and "Administration Console" could both be used to refer to a single application or to different applications. For this reason it is important that writers choose the most suitable term for each situation and use it consistently. diff --git a/en-US/N.xml b/en-US/N.xml index 4ec6a2e..c5cee83 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -10,7 +10,7 @@ navigate to - Use "Navigate to" when moving through multiple GUI options, because it covers all cases where you might have to click, point to, select, or otherwise make a series of selections to initiate an action. For example, "From the OpenShift web console, navigate to Monitoring → Alerting." + Use "Navigate to" when moving through multiple UI options, because it covers all cases where you might have to click, point to, select, or otherwise make a series of selections to initiate an action. For example, "From the OpenShift web console, navigate to Monitoring → Alerting." Do not use "Go to", or "point to", or other variations. diff --git a/en-US/T.xml b/en-US/T.xml index f255be0..159c5f3 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -228,7 +228,7 @@ Initialism for "time to live" (n.) and "time-to-live" (adj.) - Neither the noun nor the adjective should be capitalized unless you are documenting a GUI field, label, or similar element, in which case you should use the same capitalization. Capitalization at the beginning of a sentence is acceptable. The initialism is always uppercase. + Neither the noun nor the adjective should be capitalized unless you are documenting a UI field, label, or similar element, in which case you should use the same capitalization. Capitalization at the beginning of a sentence is acceptable. The initialism is always uppercase. From 1ab1a4b0f69e19dd3749438fac4ec27edd4a137a Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Thu, 13 Jan 2022 12:08:26 +0000 Subject: [PATCH 21/30] #286 Updated guidance for long commands (#333) * #286 Updated guidance for long commands * #286 Minor wording change requested by Pat --- en-US/Design.xml | 47 +++++++++++++++++++++++++++++++---------------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 9db34dc..6338244 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -311,7 +311,7 @@
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, include the commands on consecutive lines: + 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: Documenting Multiple Commands @@ -322,47 +322,51 @@ $ vi myFile.txt - If the commands are long, complex, or wrap over multiple lines, two design options are available. + If the commands are long, complex, or wrap over multiple lines, then the following design options are available. Use line continuation characters and the associated PS2 prompts. - If you are documenting commands on a different operating system, update the prompts and line continuation characters to suit. + If you are documenting commands on a different operating system, then update the prompts and line continuation characters to suit. Use neither line continuation characters nor the associated PS2 prompts. + + + + Use line continuation characters without the associated PS2 prompts. + - Do not mix these two styles. - Maintain the same style throughout your document or book. + Do not mix these styles. + Maintain the same style throughout your document, book, and product set. 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 these two designs. + You can use this option for any of these designs. - - Wrapping Long Commands with Continuation Characters - - This example uses both continuation characters and PS2 prompts. - These indicators are always used together. - +Wrapping Long Commands with Continuation Characters and PS2 Prompts + + This example uses both continuation characters and PS2 prompts. + + # tar --selinux -czvf config_files.tar.gz /etc/katello \ > /etc/elasticsearch /etc/candlepin /etc/pulp /etc/gofer \ > /etc/grinder /etc/pki/katello /etc/pki/pulp /etc/qpidd.conf \ > /etc/sysconfig/katello /etc/sysconfig/elasticsearch \ > /root/ssl–build /var/www/html/pub/* /var/lib/katello - + -Wrapping Long Commands Without Continuation Characters +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. @@ -372,9 +376,20 @@ $ vi myFile.txt --config_file=/home/user/config.conf --output_file=/home/user/output.txt - + -
+Wrapping Long Commands with Continuation Characters and Without PS2 Prompts + + This example uses continuation characters but not PS2 prompts. + +[root@node]# cephadm bootstrap --mon-ip=MON_IP --registry-url=registry.redhat.io \ +--registry-username=REGISTRY_USERNAME --registry-password=REGISTRY_PASSWORD \ +--initial-dashboard-password=DASHBOARD_PASSWORD --dashboard-password-noupdate \ +--allow-fqdn-hostname + + + +
Referring to Replaceable Paths From 8bbb5df9852d64a6104acd6b7f4912141081f4a7 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Thu, 13 Jan 2022 15:10:30 +0000 Subject: [PATCH 22/30] #304 Added entry for 'number sign' (#335) --- en-US/N.xml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/en-US/N.xml b/en-US/N.xml index c5cee83..531338a 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -107,6 +107,16 @@ + + number sign + + + Generally, use "number sign" to refer to the # character. Alternatively, use "hash" to refer to a hashtag in social media, or to refer to Secure Hash Algorithm (see ), or when writing exclusively for a European audience. You can instead use "pound sign" when writing exclusively for a North American audience, if "number sign" is not appropriate for the context. + + + + + @@ -269,7 +269,7 @@ documentation - When referring to the current manual set, use "documentation." For example, "This manual is also available as part of our online documentation." When referring to another manual, quote the title of the manual, for example, "See the Getting Started Guide for further information." + When referring to the current manual set, use "documentation". For example, "This manual is also available as part of our online documentation." When referring to another manual, quote the title of the manual, for example, "See the Getting Started Guide for further information." @@ -279,7 +279,7 @@ domain name - Correct. Do not use "domainname" or "domain-name." + Correct. Do not use "domainname" or "domain-name". A name that identifies one or more IP addresses. For example, the domain name microsoft.com represents about a dozen IP addresses. Domain names are used in URLs to identify particular web pages. For example, in the URL http://www.redhat.com/docs, the domain name is redhat.com. @@ -302,7 +302,7 @@ download - v., n. Do not use "down load" or "down-load." + v., n. Do not use "down load" or "down-load". @@ -322,7 +322,7 @@ downtime - Correct. Refers to the period during which a server, service, or other resource is unavailable. Do not use "down-time" or "down time." + Correct. Refers to the period during which a server, service, or other resource is unavailable. Do not use "down-time" or "down time". @@ -332,7 +332,7 @@ dual-boot - adj. Do not use "dualboot" or "dual boot." + adj. Do not use "dualboot" or "dual boot". diff --git a/en-US/Design.xml b/en-US/Design.xml index 6338244..42f4694 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -72,7 +72,7 @@
Documenting Fonts - The preferred way to refer to each type of PostScript font is "PostScript Type x," substituting "x" with either 1, 2, or 3, if the problem is specific to a particular type. + The preferred way to refer to each type of PostScript font is "PostScript Type x", substituting "x" with either 1, 2, or 3, if the problem is specific to a particular type.
@@ -92,7 +92,7 @@ In most cases, do not include the element 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. @@ -169,7 +169,7 @@
- "POSIX recommends these conventions for command line arguments. [...] Arguments are options if they begin with a hyphen delimiter (‘-’). Multiple options may follow a hyphen delimiter in a single token if the options do not take arguments. Thus, ‘-abc’ is equivalent to ‘-a -b -c’. [...] Certain options require an argument. For example, the ‘-o’ option of the ‘ld’ command requires an argument—an output file name." and so on. + "POSIX recommends these conventions for command line arguments. [...] Arguments are options if they begin with a hyphen delimiter (‘-’). Multiple options may follow a hyphen delimiter in a single token if the options do not take arguments. Thus, ‘-abc’ is equivalent to ‘-a -b -c’. [...] Certain options require an argument. For example, the ‘-o’ option of the ‘ld’ command requires an argument—an output file name". and so on. See info libc argument syntax for the full discussion. @@ -523,7 +523,7 @@ $ vi myFile.txt To describe how to view and edit files, such as configuration files, scripts, and so on, do not include editor names as part of the guidance, unless the topic is about a specific editor, or is otherwise necessary to achieve a wanted result. - For example, do not refer to cat or vi if you need to tell readers to "view the my-script file." If you need to tell readers to edit a file and add or remove content, write "Edit the my-script file and add the following content:" and then include the required content in a <screen> block. Use <code> tags to highlight the text to change. Include some surrounding text in the file for context. Do not use line numbers as a reference point because they can change. + For example, do not refer to cat or vi if you need to tell readers to "view the my-script file". If you need to tell readers to edit a file and add or remove content, write "Edit the my-script file and add the following content:" and then include the required content in a <screen> block. Use <code> tags to highlight the text to change. Include some surrounding text in the file for context. Do not use line numbers as a reference point because they can change. If the file to edit is empty or does not exist, do not use <code> tags to highlight any content to add. @@ -745,7 +745,7 @@ $ vi myFile.txt Abbreviations - An abbreviation is a shortened form of a word or phrase. For example, Pty. and Inc. are abbreviations for "proprietary" and "incorporated," respectively. Read them as the word for which they are an abbreviation. + An abbreviation is a shortened form of a word or phrase. For example, Pty. and Inc. are abbreviations for "proprietary" and "incorporated", respectively. Read them as the word for which they are an abbreviation. @@ -760,12 +760,12 @@ $ vi myFile.txt - Consider pronunciation when using articles. For example, use "an RTS (real-time strategy)," because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade," because RAM is an acronym and you pronounce it as a word (răm). + Consider pronunciation when using articles. For example, use "an RTS (real-time strategy)", because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade", because RAM is an acronym and you pronounce it as a word (răm). - Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ..." - Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)." + Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ...". + Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)". Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML. @@ -814,7 +814,7 @@ $ vi myFile.txt - In the following sections, "first use" refers to the first use of a name in body text. Titles, banners, and similar objects are not classified as "first use." + In the following sections, "first use" refers to the first use of a name in body text. Titles, banners, and similar objects are not classified as "first use". @@ -839,11 +839,11 @@ $ vi myFile.txt - Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was..." + Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was ...". - In this case, "Platform" is part of the product name. In other cases, words like "platform," "manager," and so on might not be part of the product name, in which case an article is acceptable, if not necessary. + In this case, "Platform" is part of the product name. In other cases, words like "platform", "manager", and so on might not be part of the product name, in which case an article is acceptable, if not necessary. @@ -1017,7 +1017,7 @@ $ vi myFile.txt
Making Recommendations - When making a recommendation, the preferred verbiage is "Red Hat recommends..." instead of the common but indirect "It is recommended...". + When making a recommendation, the preferred verbiage is "Red Hat recommends ..." instead of the common but indirect "It is recommended ...". Recommendations can include best practices, recommended practices, and product-specific suggestions. See for information on using the terms "best practices" and "recommended practices" in Red Hat documentation. @@ -1083,7 +1083,7 @@ Book Title by First name Surname; Publisher. - Do not link words within the body text. That is, do not use structures such as "Go here for more information," where "here" is a link. + Do not link words within the body text. That is, do not use structures such as "Go here for more information", where "here" is a link. diff --git a/en-US/E.xml b/en-US/E.xml index fa64967..b76ba72 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -41,7 +41,7 @@ Emacs - If referring to the program, use "Emacs." For example, "Source-Navigator supports Emacs or vi commands." If referring to the shell prompt command, use "emacs." For example, "At the prompt, type emacs." The complete and correct name is "GNU Emacs." + If referring to the program, use "Emacs". For example, "Source-Navigator supports Emacs or vi commands". If referring to the shell prompt command, use "emacs". For example, "At the prompt, type emacs." The complete and correct name is "GNU Emacs". @@ -68,7 +68,7 @@ When referring to typing a command, use "type" instead, such as "To open Source-Navigator from the command line, type snavigator." - When typing information into a single-field dialog box, "enter" means "type and press Enter." An example is "enter the license number." For multi-field dialog boxes, see "type." + When typing information into a single-field dialog box, "enter" means "type and press Enter". An example is "enter the license number". For multi-field dialog boxes, see "type". @@ -162,7 +162,7 @@ Exif - Correct. Do not use "EXIF." Exif is an image file format specification that enables adding metadata tags to existing JPEG, TIFF, and RIFF files. Sometimes referred to as "Exif Print." + Correct. Do not use "EXIF". Exif is an image file format specification that enables adding metadata tags to existing JPEG, TIFF, and RIFF files. Sometimes referred to as "Exif Print". diff --git a/en-US/Easily_Confused_Words.xml b/en-US/Easily_Confused_Words.xml index 53bf144..ef02831 100644 --- a/en-US/Easily_Confused_Words.xml +++ b/en-US/Easily_Confused_Words.xml @@ -39,7 +39,7 @@ v. Means to produce a result, or to cause something to happen. For example, "the CEO claimed that the new policy would effect a positive economic outcome." - The use of "effect" as a verb is less common than the use of "affect," and there are usually alternatives that are clearer. For example, "the CEO claimed that the new policy would produce a positive economic outcome." + The use of "effect" as a verb is less common than the use of "affect", and there are usually alternatives that are clearer. For example, "the CEO claimed that the new policy would produce a positive economic outcome." diff --git a/en-US/F.xml b/en-US/F.xml index c840078..94f6486 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -41,7 +41,7 @@ FAQ - When referring to a Frequently Asked Questions (FAQ) section of content, refer to it as "an FAQ" (to be read as "an F") not "a FAQ." The plural form is "FAQs." + When referring to a Frequently Asked Questions (FAQ) section of content, refer to it as "an FAQ" (to be read as "an F") not "a FAQ". The plural form is "FAQs". @@ -107,7 +107,7 @@ n. Write as shown, two words, unless used as a variable. See the IBM Style Guide for more information. - adj. Hyphenate when used as a compound adjective. For example, "file-system attributes." + adj. Hyphenate when used as a compound adjective. For example, "file-system attributes". @@ -117,7 +117,7 @@ FireWire - Correct. Do not use "Firewire" or "firewire." Although FireWire is a trademark of Apple Computer, it is not needed to append a trademark symbol, except to refer to Apple's FireWire software license or specific logos. See https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html. + Correct. Do not use "Firewire" or "firewire". Although FireWire is a trademark of Apple Computer, it is not needed to append a trademark symbol, except to refer to Apple's FireWire software license or specific logos. See https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html. @@ -128,7 +128,7 @@ firmware - n. Do not use "firm ware" or "firm-ware." + n. Do not use "firm ware" or "firm-ware". Software (programs or data) that is written onto read-only memory (ROM). Firmware is a combination of software and hardware. ROMs, PROMs, and EPROMs that have data or programs recorded on them are firmware. @@ -152,7 +152,7 @@ floppy disk - Do not use. Use "diskette," and also state the size of the diskette, such as "3.5 in. diskette." + Do not use. Use "diskette", and also state the size of the diskette, such as "3.5 in. diskette". @@ -162,7 +162,7 @@ floppy drive - Do not use. Use "diskette drive." + Do not use. Use "diskette drive". @@ -223,7 +223,7 @@ FORTRAN - Correct. Do not use "Fortran." + Correct. Do not use "Fortran". @@ -233,7 +233,7 @@ forward - Correct. Avoid using "forwards." + Correct. Avoid using "forwards". @@ -243,7 +243,7 @@ forwards compatible - Do not use. Instead, use "compatible with later versions." See also . + Do not use. Instead, use "compatible with later versions". See also . @@ -308,7 +308,7 @@ futexes - Correct. "Futex" is an abbreviation of "fast user-space mutex." Consequently, "futexes" is the correct plural form. + Correct. "Futex" is an abbreviation of "fast user-space mutex". Consequently, "futexes" is the correct plural form. diff --git a/en-US/G.xml b/en-US/G.xml index 35892e8..fb223ab 100644 --- a/en-US/G.xml +++ b/en-US/G.xml @@ -33,10 +33,10 @@ Abbreviation of gigabyte. Depending on the type of content you are writing, refer either to The AP Style Guide or the IBM Style Guide. - AP style: Do not use a space between the value and the abbreviation. For example, "a 2GB file." + AP style: Do not use a space between the value and the abbreviation. For example, "a 2GB file". - IBM style: Use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file." + IBM style: Use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file". @@ -126,7 +126,7 @@ GID - Acronym for Group ID. Do not use "gid." + Acronym for Group ID. Do not use "gid". @@ -136,7 +136,7 @@ gigabyte - 2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. When abbreviating "gigabyte," use "GB." Use a non-breaking space between the unit and any value to prevent widows and orphans. + 2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. When abbreviating "gigabyte", use "GB". Use a non-breaking space between the unit and any value to prevent widows and orphans. @@ -156,7 +156,7 @@ GIMP - Acronym for GNU Image Manipulation Program. Do not use "Gimp" or "gimp." + Acronym for GNU Image Manipulation Program. Do not use "Gimp" or "gimp". @@ -166,7 +166,7 @@ GNOME - Correct. Do not use "gnome," "Gnome," or other variants. See also . + Correct. Do not use "gnome", "Gnome", or other variants. See also . @@ -186,7 +186,7 @@ GNU - Recursive initialism for "GNU's Not UNIX." Do not use "Gnu" or "gnu." + Recursive initialism for "GNU's Not UNIX". Do not use "Gnu" or "gnu". @@ -216,7 +216,7 @@ GPL - Initialism for General Public License. Do not use "Gpl" or "gpl." + Initialism for General Public License. Do not use "Gpl" or "gpl". @@ -226,7 +226,7 @@ grayscale - n. Correct. Do not use "gray-scale" or "gray scale." Only the noun form is currently recognized. + n. Correct. Do not use "gray-scale" or "gray scale". Only the noun form is currently recognized. @@ -236,7 +236,7 @@ GRUB - Correct. All caps. Do not use "Grub." + Correct. All caps. Do not use "Grub". @@ -246,7 +246,7 @@ GTK+ - Initialism for GIMP Tool Kit. Do not use "GTK," "Gtk," or "gtk." + Initialism for GIMP Tool Kit. Do not use "GTK", "Gtk", or "gtk". diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index a3389ef..1a65572 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -11,7 +11,7 @@
Active Voice - Use the active voice ("Type ... to start Linuxconf.") rather than passive ("Linuxconf can be started by typing...") whenever possible. Active voice makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count. + Use the active voice ("Type ... to start Linuxconf".) rather than passive ("Linuxconf can be started by typing ...") whenever possible. Active voice makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count. This does not mean that the passive voice is forbidden. There are situations when using the passive voice is appropriate, such as release notes, technical notes, and similar material. @@ -111,7 +111,7 @@
Using Who, Whom, That, and Which Correctly - Use "whom" or "who" to introduce a qualifying phrase when the antecedent is a person. Use "that" or "which" when referring to a thing. Use "which" or "that" to introduce a qualifying phrase when the antecedent is a concept or an object. Who, whom, that, and which are known as "relative pronouns." + Use "whom" or "who" to introduce a qualifying phrase when the antecedent is a person. Use "that" or "which" when referring to a thing. Use "which" or "that" to introduce a qualifying phrase when the antecedent is a concept or an object. Who, whom, that, and which are known as "relative pronouns". Use the following as guidelines: @@ -177,7 +177,7 @@ - Edward C. Bailey, who wrote "Maximum RPM,"... + Edward C. Bailey, who wrote "Maximum RPM",... @@ -530,11 +530,11 @@ Split contractions and abbreviations into separate paragraphs. -->
Contractions and Abbreviations - Do not use contractions in Red Hat documents. For example, do not use "can't," "don't," "won't," and similar examples. Write out the words in full. Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. They can also cause problems for translation. + Do not use contractions in Red Hat documents. For example, do not use "can't", "don't", "won't", and similar examples. Write out the words in full. Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. They can also cause problems for translation. - Take care also with abbreviations; replace "e.g." with "for example," and replace "i.e." with "that is," and so on. + Take care also with abbreviations; replace "e.g." with "for example", and replace "i.e." with "that is", and so on.
@@ -548,7 +548,7 @@ Split contractions and abbreviations into separate paragraphs. --> Hyphenate for Clarity - Hyphenate when needed for clarity. Words that begin with prefixes are usually not hyphenated. Prefixes can include "multi," "non," "sub," "co," "semi," "pre," "re," and so on. The same applies to suffixes; for example, "less" as a suffix does not require hyphenation. + Hyphenate when needed for clarity. Words that begin with prefixes are usually not hyphenated. Prefixes can include "multi", "non", "sub", "co", "semi", "pre", "re", and so on. The same applies to suffixes; for example, "less" as a suffix does not require hyphenation. @@ -570,7 +570,7 @@ Split contractions and abbreviations into separate paragraphs. --> - Do not hyphenate "open source," even when used as a complex adjective. + Do not hyphenate "open source", even when used as a complex adjective. Do not hyphenate a compound that includes an adverb ending in -ly, whether it comes before or after the noun. This is described in Chicago Manual of Style 7.82. @@ -609,7 +609,7 @@ Split contractions and abbreviations into separate paragraphs. -->
Gender References - Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers." It is acceptable to use "they" to refer to one person, with a plural verb. In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. + Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers". It is acceptable to use "they" to refer to one person, with a plural verb. In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person.
diff --git a/en-US/H.xml b/en-US/H.xml index fc7bf97..dea3153 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -37,7 +37,7 @@ hard disk - n. Correct. Do not use "harddisk" or "hard-disk." + n. Correct. Do not use "harddisk" or "hard-disk". @@ -47,7 +47,7 @@ hard disk drive - n. Correct. Do not use "harddrive" or "hard-drive." + n. Correct. Do not use "harddrive" or "hard-drive". @@ -120,7 +120,7 @@ hertz - n. Correct. Capitalize the "H" only at the beginning of a sentence. The correct abbreviation is "Hz." + n. Correct. Capitalize the "H" only at the beginning of a sentence. The correct abbreviation is "Hz". @@ -131,8 +131,8 @@ high-availability, high availability - adj. Hyphenate, except as part of a product name. For example, "high-availability cluster." - + adj. Hyphenate, except as part of a product name. For example, "high-availability cluster". + @@ -188,7 +188,7 @@ hot add - v. Two words, lowercase. Capitalize only at the beginning of a sentence. Do not use "hotadd" or "hot-add." + v. Two words, lowercase. Capitalize only at the beginning of a sentence. Do not use "hotadd" or "hot-add". @@ -209,7 +209,7 @@ hot plug - v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotplug" or "hot-plug." + v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotplug" or "hot-plug". @@ -219,7 +219,7 @@ hot swap - v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotswap" or "hot-swap." + v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotswap" or "hot-swap". @@ -249,7 +249,7 @@ HTML - When referring to the language, use "HTML," such as "To see the HTML version of this documentation ..." When referring to a web page extension, use "html," such as "The main page is index.html." + When referring to the language, use "HTML", such as "To see the HTML version of this documentation ...". When referring to a web page extension, use "html", such as "The main page is index.html." @@ -292,7 +292,7 @@ hypervisor - n. Capitalize only at the beginning of a sentence or as part of Red Hat Virtualization Hypervisor. Do not use "HyperVisor" or "Hyperviser." + n. Capitalize only at the beginning of a sentence or as part of Red Hat Virtualization Hypervisor. Do not use "HyperVisor" or "Hyperviser". diff --git a/en-US/I.xml b/en-US/I.xml index 484aca1..1408dac 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -20,7 +20,7 @@ IaaS - Correct. This is the correct abbreviation for "Infrastructure-as-a-Service." See also . + Correct. This is the correct abbreviation for "Infrastructure-as-a-Service". See also . @@ -42,7 +42,7 @@ IBM eServer System p - "IBM eServer System p" is correct for the first reference in a manual. Use "IBM System p" or "System p" for subsequent references. Do not use "pSeries." + "IBM eServer System p" is correct for the first reference in a manual. Use "IBM System p" or "System p" for subsequent references. Do not use "pSeries". @@ -73,7 +73,7 @@ illegal - Illegal means "prohibited by law," not "incorrect" or "not permitted." Use "invalid" or a related word. + Illegal means "prohibited by law", not "incorrect" or "not permitted". Use "invalid" or a related word. @@ -85,7 +85,7 @@ indexes - Correct. This is the correct plural form for US English spelling. Do not use "indices." + Correct. This is the correct plural form for US English spelling. Do not use "indices". @@ -119,7 +119,7 @@ insecure - adj. Correct. Do not use "nonsecure" or "non-secure." + adj. Correct. Do not use "nonsecure" or "non-secure". @@ -139,10 +139,10 @@ Intel 64 - Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86," or other variations as the name of this architecture. + Correct. Do not use "Hammer", "x86_64", "x86-64", "x64", "64-bit x86", or other variations as the name of this architecture. - The correct term for Intel's implementation of this architecture is "Intel® 64." + The correct term for Intel's implementation of this architecture is "Intel® 64". When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. @@ -179,7 +179,7 @@ Intel Tolapai / Intel® EP80579 Integrated Processor - Do not use the code-name, "Tolapai." Use the official brand name "Intel® EP80579 Integrated Processor." + Do not use the code-name, "Tolapai". Use the official brand name "Intel® EP80579 Integrated Processor". @@ -189,10 +189,10 @@ Intel Virtualization Technology (Intel VT) - Correct. The first and all prominent uses of the name should be fully spelled out, immediately followed by the initialism. For example, "Intel Virtualization Technology (Intel VT) for Intel 64 or Itanium architecture (Intel Vi). Subsequent uses can be abbreviated to "Intel Vi." + Correct. The first and all prominent uses of the name should be fully spelled out, immediately followed by the initialism. For example, "Intel Virtualization Technology (Intel VT) for Intel 64 or Itanium architecture (Intel Vi). Subsequent uses can be abbreviated to "Intel Vi". - Always write the initialism in uppercase, accompanied by the "Intel" mark. Do not use "Vi" or "VT." Do not use the initialism in any prominent places, such as in titles or paragraph headings, and do not include any trademark symbols, such as ™ or "(TM)." + Always write the initialism in uppercase, accompanied by the "Intel" mark. Do not use "Vi" or "VT". Do not use the initialism in any prominent places, such as in titles or paragraph headings, and do not include any trademark symbols, such as ™ or "(TM)". @@ -213,7 +213,7 @@ interesting - Avoid this term, because it is a substitute for showing the reader why something is of interest. For example, instead of writing "It is interesting to note...", consider using a "Note" admonition. + Avoid this term, because it is a substitute for showing the reader why something is of interest. For example, instead of writing "It is interesting to note ...", consider using a "Note" admonition. @@ -305,7 +305,7 @@ IPsec - IPsec stands for Internet Protocol security. According to its RFC, IPsec should be used. Do not use "IPSec." + IPsec stands for Internet Protocol security. According to its RFC, IPsec should be used. Do not use "IPSec". @@ -335,7 +335,7 @@ IT/I.T. - Use "I.T." (with periods) only in headlines or subheadings where all caps are used, to clarify that the word is "IT" versus "it." + Use "I.T." (with periods) only in headlines or subheadings where all caps are used, to clarify that the word is "IT" versus "it". @@ -364,7 +364,7 @@ Itanium 2 - Itanium 2 is correct. Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2." + Itanium 2 is correct. Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2". @@ -376,7 +376,7 @@ ISeries - IBM eServer System i is correct for the first reference in a manual; use IBM System i or System i for subsequent references. Do not use "iSeries." + IBM eServer System i is correct for the first reference in a manual; use IBM System i or System i for subsequent references. Do not use "iSeries". diff --git a/en-US/J.xml b/en-US/J.xml index 28be68f..98b4790 100644 --- a/en-US/J.xml +++ b/en-US/J.xml @@ -10,7 +10,7 @@ JavaScript - "JavaScript" is a trademark of Oracle Corporation, and should be used when referring to the scripting language. When referring to a file that is written with this language, use all lowercase; for example, "...copy the IPA javascript file to the /temp directory." + "JavaScript" is a trademark of Oracle Corporation, and should be used when referring to the scripting language. When referring to a file that is written with this language, use all lowercase; for example, "...copy the IPA javascript file to the /temp directory". @@ -20,7 +20,7 @@ JBoss Community - No longer referred to as "JBoss.org." Use when referring to the community of users and contributors. + No longer referred to as "JBoss.org". Use when referring to the community of users and contributors. @@ -50,7 +50,7 @@ just - Use sparingly. In the phrase, "Just open the file...", omit the word "just." + Use sparingly. In the phrase, "Just open the file ...", omit the word "just". @@ -60,7 +60,7 @@ JVM - Initialism for Java Virtual Machine, and a registered trademark of Oracle Corporation. Due to this registration, rather than using "JVM" as a noun when referring to the virtual machine, use the full phrase "Java Virtual Machine," or "Java VM," or only the noun itself, "virtual machine." You can include "JVM" for clarity, because most people know it as such, for example, "Java Virtual Machine (JVM)." Do not use Jvm or jvm. + Initialism for Java Virtual Machine, and a registered trademark of Oracle Corporation. Due to this registration, rather than using "JVM" as a noun when referring to the virtual machine, use the full phrase "Java Virtual Machine", or "Java VM", or only the noun itself, "virtual machine". You can include "JVM" for clarity, because most people know it as such, for example, "Java Virtual Machine (JVM)". Do not use Jvm or jvm. diff --git a/en-US/K.xml b/en-US/K.xml index 8a8b51d..dcad72e 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -33,7 +33,7 @@ kerberize - Incorrect. Do not use "kerberize," "kerberized," or other variants to refer to applications or services that use Kerberos authentication. Refer to such applications as "Kerberos-aware" or "Kerberos-enabled," or rewrite the sentence. + Incorrect. Do not use "kerberize", "kerberized", or other variants to refer to applications or services that use Kerberos authentication. Refer to such applications as "Kerberos-aware" or "Kerberos-enabled", or rewrite the sentence. @@ -76,7 +76,7 @@ n. Two words when used as a noun. - adj. Hyphenate as an adjective, "kernel-space." Do not use "kernelspace." + adj. Hyphenate as an adjective, "kernel-space". Do not use "kernelspace". @@ -86,7 +86,7 @@ keyboard key - When referring to a keyboard key, it is uppercase, singular, and the word "key" is not necessary, such as "To exit, press X." When the Ctrl or Alt keys are needed, use a plus sign between the keys, such as "To save the file, press "Ctrl+S." + When referring to a keyboard key, it is uppercase, singular, and the word "key" is not necessary, such as "To exit, press X". When the Ctrl or Alt keys are needed, use a plus sign between the keys, such as "To save the file, press "Ctrl+S". See also . @@ -99,13 +99,13 @@ key ring - n. Use the two-word form as a noun. For example, "add your new key to the key ring." + n. Use the two-word form as a noun. For example, "add your new key to the key ring". - adj. Use the hyphenated form as an adjective. For example, "copy the key-ring file to the server." + adj. Use the hyphenated form as an adjective. For example, "copy the key-ring file to the server". - Only use the one-word form, "keyring," if it is the actual name of a command, package, or other proper noun. + Only use the one-word form, "keyring", if it is the actual name of a command, package, or other proper noun. @@ -125,7 +125,7 @@ key-value - adj. Correct when referring to a data representation in computing systems and applications, for example a "key-value pair." Do not use "key/value" or any other variations. + adj. Correct when referring to a data representation in computing systems and applications, for example a "key-value pair". Do not use "key/value" or any other variations. @@ -148,7 +148,7 @@ kill - If terminating a UNIX process, use "kill." For example, to terminate the process, type kill <PID>. If terminating a Windows process, use "terminate." For example, "To terminate the process, press Q." + If terminating a UNIX process, use "kill". For example, to terminate the process, type kill <PID>. If terminating a Windows process, use "terminate". For example, "To terminate the process, press Q." @@ -158,7 +158,7 @@ knowledge base - Correct. Use the two-word form unless referring specifically to the "Red Hat Knowledgebase." In this case, use the one-word form and capitalize the "K." Do not capitalize the "b." + Correct. Use the two-word form unless referring specifically to the "Red Hat Knowledgebase". In this case, use the one-word form and capitalize the "K". Do not capitalize the "b". diff --git a/en-US/L.xml b/en-US/L.xml index 8cf9568..bbd920b 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -62,7 +62,7 @@ left-click - v. Write the term hyphenated. Do not use "left click" or "leftclick." + v. Write the term hyphenated. Do not use "left click" or "leftclick". @@ -74,7 +74,7 @@ LibreOffice - A Linux desktop suite. Do not use "Libre," "Libreoffice," or "Libre Office." + A Linux desktop suite. Do not use "Libre", "Libreoffice", or "Libre Office". See also @@ -218,7 +218,7 @@ v. Use the two-word form. - adj. Hyphenate when used as a modifier. For example, "a look-up table." + adj. Hyphenate when used as a modifier. For example, "a look-up table". diff --git a/en-US/Language.xml b/en-US/Language.xml index 31bb084..5ce9a32 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -30,7 +30,7 @@ best practices - This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices." + This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices". See the section for additional information about recommendations in Red Hat documentation. @@ -42,7 +42,7 @@ first come, first served - Indicates that customers will be attended to in the order that they arrive. The phrase abbreviates the sentence "The first to come is the first to be served," so use "served" instead of "serve" to keep the verb function the same. This phrase is an idiom, so avoid using it when content will be translated. When you use this phrase as an adjective, it is hyphenated as follows: Admittance is on a first-come, first-served basis. + Indicates that customers will be attended to in the order that they arrive. The phrase abbreviates the sentence "The first to come is the first to be served", so use "served" instead of "serve" to keep the verb function the same. This phrase is an idiom, so avoid using it when content will be translated. When you use this phrase as an adjective, it is hyphenated as follows: Admittance is on a first-come, first-served basis. @@ -107,7 +107,7 @@ at this point in time - Do not use. In most cases, use "now." In some cases it is acceptable to use "at this point," for example, when you have reached a specific point in a procedure. + Do not use. In most cases, use "now". In some cases it is acceptable to use "at this point", for example, when you have reached a specific point in a procedure. @@ -127,7 +127,7 @@ best-of-breed - Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type." Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. + Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type". Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. @@ -158,7 +158,7 @@ bucketize - Not a word. Try "categorize" or "organize into logical groups." + Not a word. Try "categorize" or "organize into logical groups". @@ -178,7 +178,7 @@ check this site - Understood to mean "have a look at this website." The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. + Understood to mean "have a look at this website". The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. @@ -189,7 +189,7 @@ core competency - Jargon, cold and impersonal. Better choices include "specialization," "skill," "strength," "expertise," and so on. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." + Jargon, cold and impersonal. Better choices include "specialization", "skill", "strength", "expertise", and so on. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." @@ -219,7 +219,7 @@ dig deeper, delve deeper - "Visit the following web link to dig deeper into [subject]..." Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." + "Visit the following web link to dig deeper into [subject] ...". Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." @@ -259,8 +259,8 @@ fib - A fib is a "small lie," also known as a "white lie." - For example, "This command tells fibs" is better written as "The output of this command can be misleading." + A fib is a "small lie", also known as a "white lie". + For example, "This command tells fibs" is better written as "The output of this command can be misleading". @@ -270,7 +270,7 @@ flying by the seat of your pants - Generally understood to mean "reacting to events as they occur." Difficult to offer alternatives without context. + Generally understood to mean "reacting to events as they occur". Difficult to offer alternatives without context. @@ -290,7 +290,7 @@ frown upon - "To frown upon" means to hold in low regard, not to approve of, and so on. For example: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). + "To frown upon" means to hold in low regard, not to approve of, and so on. For example: "... we generally frown on the use of session context ...". This translates to (and should have been written as) "... the use of session context is not recommended ..." (or words to that effect). @@ -305,7 +305,7 @@ - In Directory Server, if you do a fuzzy search for "Smith," you will probably also get "Smyth," because it sounds the same. + In Directory Server, if you do a fuzzy search for "Smith", you will probably also get "Smyth", because it sounds the same. @@ -315,7 +315,7 @@ The use of "fuzzy" is valid in this context. - Note the difference between this and "wildcard" searches: "Sm?th" could return "Smith," "Smyth," "Smeth," or even "Smrth." + Note the difference between this and "wildcard" searches: "Sm?th" could return "Smith", "Smyth", "Smeth", or even "Smrth". Do not use "fuzzy" to describe something that is not clear, such as an image, a concept, an idea, and so on. For example, "He was a bit fuzzy on the details" is not valid. @@ -328,7 +328,7 @@ going-forward basis - Jargon. Say "from now on," "in the future," or something similar. + Jargon. Say "from now on", "in the future", or something similar. @@ -358,7 +358,7 @@ have a crack at, jump right in - Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try." Alternatives to these are "start," "try," and "begin," and will depend on the context of what is being discussed. + Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try". Alternatives to these are "start", "try", and "begin", and will depend on the context of what is being discussed. @@ -368,7 +368,7 @@ if you want, if you wish - Do not use. For example, instead of saying "If you want to perform an action,..." say "To perform an action,..." + Do not use. For example, instead of saying "If you want to perform an action, ..." say "To perform an action, ...". @@ -378,7 +378,7 @@ in concert with - Do not use. Instead, say "with." For example, change "Use gcov in concert with GCC to analyze..." to "Use gcov with GNU CC to analyze..." + Do not use. Instead, say "with". For example, change "Use gcov in concert with GCC to analyze ..." to "Use gcov with GNU CC to analyze ..." @@ -434,7 +434,7 @@ kettle of fish - Commonly used in the expression "a different kettle of fish," meaning "that's a different matter (altogether)." Depending on the context, try to use "topic," "subject," "matter," or something similar. + Commonly used in the expression "a different kettle of fish", meaning "that's a different matter (altogether)". Depending on the context, try to use "topic", "subject", "matter", or something similar. @@ -478,7 +478,7 @@ meet your needs - Vague. Try to be more specific, for example, "lower your middleware costs." + Vague. Try to be more specific, for example, "lower your middleware costs". @@ -498,7 +498,7 @@ net-net - Jargon. Use "in summary," "the end result," or something similar. + Jargon. Use "in summary", "the end result", or something similar. @@ -518,7 +518,7 @@ over the wire - Commonly used in expressions such as "password information is sent in plain text over the wire," meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent or transmitted in plain text" is fine. + Commonly used in expressions such as "password information is sent in plain text over the wire", meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent or transmitted in plain text" is fine. @@ -529,7 +529,7 @@ paradigm - Avoid. Use "model," "standard," or something similar. + Avoid. Use "model", "standard", or something similar. @@ -539,7 +539,7 @@ performant - In the technical industry context, it means "performs as expected" or "well-performing." It is not necessarily a word everyone knows (and technically, it means "a performer," as in a play, according to most dictionaries), so use an alternative if possible. + In the technical industry context, it means "performs as expected" or "well-performing". It is not necessarily a word everyone knows (and technically, it means "a performer", as in a play, according to most dictionaries), so use an alternative if possible. @@ -560,7 +560,7 @@ pre-baked, prebaked - Means "prepared beforehand." Choose a suitable alternative, such as "preconfigured," depending on the context. + Means "prepared beforehand". Choose a suitable alternative, such as "preconfigured", depending on the context. @@ -568,7 +568,7 @@ productize - Not a word. Find another way to say "modify something to become suitable as a commercial product." [wiktionary] + Not a word. Find another way to say "modify something to become suitable as a commercial product". [wiktionary] @@ -578,7 +578,7 @@ ready to rumble - "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start." + "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start". @@ -598,7 +598,7 @@ right before doing something - Preferred phrase would be "immediately before doing something." Otherwise, write around the phrase. + Preferred phrase would be "immediately before doing something". Otherwise, write around the phrase. @@ -620,7 +620,7 @@ shoot yourself in the foot - To "shoot yourself in the foot" indicates that you did something to harm your own cause, or acting against your own best interests. Remove the sentence; it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes.") + To "shoot yourself in the foot" indicates that you did something to harm your own cause, or acting against your own best interests. Remove the sentence; it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes".) @@ -630,7 +630,7 @@ shy of - Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark," meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have fewer than the minimum required number. Avoid this terminology and use more easily understood terms; it will help translators and also those reading English documentation who are unfamiliar with such slang. + Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark", meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have fewer than the minimum required number. Avoid this terminology and use more easily understood terms; it will help translators and also those reading English documentation who are unfamiliar with such slang. @@ -640,7 +640,7 @@ silo, siloed - Use "stand-alone," "confined," "separated," or something similar. + Use "stand-alone", "confined", "separated", or something similar. @@ -673,7 +673,7 @@ stovepipe - Jargon. In business, related to lack of cross-organizational communication, similar to "silo." + Jargon. In business, related to lack of cross-organizational communication, similar to "silo". @@ -683,7 +683,7 @@ synergistic, synergy - Jargon. Use "cooperative," "working together," "collaborative," "harmonious," or something similar. + Jargon. Use "cooperative", "working together", "collaborative", "harmonious", or something similar. @@ -724,7 +724,7 @@ value-added - Jargon. Say "added value" or "valuable." Or be more specific, for example, "adds value by improving productivity." + Jargon. Say "added value" or "valuable". Or be more specific, for example, "adds value by improving productivity". @@ -734,7 +734,7 @@ very - Use with caution. For example, there is little value in saying "very cost-effective" versus "cost-effective." + Use with caution. For example, there is little value in saying "very cost-effective" versus "cost-effective". @@ -744,7 +744,7 @@ virtual elephants - This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture." Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet," "dark horse," "black sheep," and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. See http://en.wikipedia.org/wiki/Blind_Men-anElephant for more information. + This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture". Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet", "dark horse", "black sheep", and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. See http://en.wikipedia.org/wiki/Blind_Men-anElephant for more information. @@ -768,7 +768,7 @@ - This sentence converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..." + This sentence converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations ..." @@ -857,7 +857,7 @@ - It is quite common to say "talk to" in this context, but "communicate with," "connected to," "registered with," or something similar would be better. + It is quite common to say "talk to" in this context, but "communicate with", "connected to", "registered with", or something similar would be better. diff --git a/en-US/M.xml b/en-US/M.xml index c28b479..63d7d08 100644 --- a/en-US/M.xml +++ b/en-US/M.xml @@ -22,7 +22,7 @@ make sure - This means "be careful to remember, attend to, or find out something." For example, "make sure that the rhedk group is listed in the output." + This means "be careful to remember, attend to, or find out something". For example, "make sure that the rhedk group is listed in the output." You might be able to use "verify" or "ensure" instead. @@ -35,7 +35,7 @@ manual, man page - Correct. Two words. Do not use "manpage." + Correct. Two words. Do not use "manpage". @@ -58,7 +58,7 @@ matrixes - Correct. This is the correct plural form for US English spelling. Do not use "matrices." + Correct. This is the correct plural form for US English spelling. Do not use "matrices". @@ -111,7 +111,7 @@ MDOS - Correct. Do not use "ms-dos," "MSDOS," or "msdos." + Correct. Do not use "ms-dos", "MSDOS", or "msdos". @@ -150,7 +150,7 @@ menu-driven - adj. Correct. Do not use "menu driven" or "menudriven." + adj. Correct. Do not use "menu driven" or "menudriven". Refers to programs whose user interface employs menus. The antithesis of a menu-driven program is a command-driven program. @@ -163,10 +163,10 @@ message - n. Write "the system displays a message" or "send an instant message." + n. Write "the system displays a message" or "send an instant message". - adj. For example, "A messaging system." + adj. For example, "A messaging system". Do not use as a verb. @@ -179,7 +179,7 @@ metadata - Correct. Do not use "meta data" or "meta-data." + Correct. Do not use "meta data" or "meta-data". @@ -199,7 +199,7 @@ Microsoft - Correct. Do not use "MS," "MSFT," or "MicroSoft." + Correct. Do not use "MS", "MSFT", or "MicroSoft". @@ -219,7 +219,7 @@ Montecito - Do not use. It is a code name for the "Intel Itanium Processor 9000 Sequence." This latter phrase should be used instead. + Do not use. It is a code name for the "Intel Itanium Processor 9000 Sequence". This latter phrase should be used instead. @@ -254,7 +254,7 @@ mouse button - n. Two words. Do not use "mouse-button" or "mousebutton." If you need to indicate which mouse button, use "right," "left," or "center," such as "right mouse button." Do not hyphenate. + n. Two words. Do not use "mouse-button" or "mousebutton". If you need to indicate which mouse button, use "right", "left", or "center", such as "right mouse button". Do not hyphenate. @@ -264,7 +264,7 @@ Mozilla Firefox - Correct. First reference must be "Mozilla Firefox." Subsequent references can be "Firefox." + Correct. First reference must be "Mozilla Firefox". Subsequent references can be "Firefox". @@ -274,7 +274,7 @@ Mozilla Thunderbird - Correct. First reference must be "Mozilla Thunderbird." Subsequent references can be "Thunderbird." + Correct. First reference must be "Mozilla Thunderbird". Subsequent references can be "Thunderbird". @@ -284,7 +284,7 @@ multiprocessing - Correct. Do not use "multi-processing." + Correct. Do not use "multi-processing". @@ -304,7 +304,7 @@ mutexes - Correct. "Mutex" is an abbreviation of "mutual exclusion." Consequently, "mutexes" is the correct plural form. + Correct. "Mutex" is an abbreviation of "mutual exclusion". Consequently, "mutexes" is the correct plural form. @@ -315,7 +315,7 @@ MySQL - Common open source database server and client package. Do not use "MYSQL" or "mySQL." Mark the first mention of MySQL in body text with an + Common open source database server and client package. Do not use "MYSQL" or "mySQL". Mark the first mention of MySQL in body text with an ® symbol to denote a registered trademark. diff --git a/en-US/N.xml b/en-US/N.xml index 531338a..94d16d7 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -22,7 +22,7 @@ needs, needs to be, need to - Avoid when possible. Suggested alternatives include "must" or "required." + Avoid when possible. Suggested alternatives include "must" or "required". @@ -101,7 +101,7 @@ NULL or null - When a command or value is stated, use NULL. When stating that something is null, use "null," all lowercase. + When a command or value is stated, use NULL. When stating that something is null, use "null", all lowercase. diff --git a/en-US/O.xml b/en-US/O.xml index b0a021f..5b05a69 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -10,7 +10,7 @@ Objective C - Correct. Do not use "Objective-C." + Correct. Do not use "Objective-C". @@ -20,7 +20,7 @@ object-oriented - Correct. Do not use "object oriented," "objectoriented," or "object-orientated." It is a modifier, such as "Java is an object-oriented language." + Correct. Do not use "object oriented", "objectoriented", or "object-orientated". It is a modifier, such as "Java is an object-oriented language". @@ -41,7 +41,7 @@ offline - adj. Write as one word. Do not use "off-line." + adj. Write as one word. Do not use "off-line". @@ -54,7 +54,7 @@ Correct. Use this term to refer to backing up a database while the database is not being accessed by applications. Do not use "cold backup" or any other variations. - The counterpart to this term is "online backup," to refer to the process of backing up a database while it is being accessed by other applications. Do not use "hot backup" or any other variations. + The counterpart to this term is "online backup", to refer to the process of backing up a database while it is being accessed by other applications. Do not use "hot backup" or any other variations. @@ -109,7 +109,7 @@ plug-in - n. Write hyphenated. Do not use "plugin." + n. Write hyphenated. Do not use "plugin". A hardware or software module that adds a specific feature or service to a larger system. @@ -137,7 +137,7 @@ pop-up - n, adj. Do not use "popup" or "pop up." + n, adj. Do not use "popup" or "pop up". @@ -147,10 +147,10 @@ POSIX - n. Do not use "Posix," "posix," or variations thereof. + n. Do not use "Posix", "posix", or variations thereof. - An acronym for "Portable Operating System Interface for UNIX." + An acronym for "Portable Operating System Interface for UNIX". @@ -160,7 +160,7 @@ PostScript - n. It is a registered trademark of Adobe. Do not use "Postscript." + n. It is a registered trademark of Adobe. Do not use "Postscript". @@ -186,7 +186,7 @@ PPP - n. Do not use "ppp" or "Ppp." + n. Do not use "ppp" or "Ppp". An initialism for Point-to-Point Protocol. @@ -225,7 +225,7 @@ - Do not use "proof of concepts." + Do not use "proof of concepts". @@ -241,7 +241,7 @@ pseudo-ops - Correct. Do not use "pseudo ops" or "pseudoops." + Correct. Do not use "pseudo ops" or "pseudoops". @@ -252,7 +252,7 @@ pSeries - n. "IBM eServer System p" is correct for the first reference in a manual; use IBM System p or System p for subsequent references. Do not use "pSeries." + n. "IBM eServer System p" is correct for the first reference in a manual; use IBM System p or System p for subsequent references. Do not use "pSeries". @@ -262,7 +262,7 @@ pull-down - adj. Use only if you must specify the type of menu or list. Do not use "pulldown." + adj. Use only if you must specify the type of menu or list. Do not use "pulldown". @@ -307,7 +307,7 @@ PXE - Short for Pre-Boot Execution Environment. Pronounced "pixie," PXE is one of the components of Intel's Wired for Management (WfM) specification. With PXE, a workstation can boot from a server on a network in preference to booting the operating system on the local hard drive. + Short for Pre-Boot Execution Environment. Pronounced "pixie", PXE is one of the components of Intel's Wired for Management (WfM) specification. With PXE, a workstation can boot from a server on a network in preference to booting the operating system on the local hard drive. PXE is a mandatory element of the WfM specification. To be considered compliant, PXE must be supported by the computer's BIOS and its NIC. diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 7b70a67..67c3a96 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -256,7 +256,7 @@ - That sentence is acceptable, but adding a comma before "...but we still stayed up..." would provide a pause and avoid the chance of having it read like a run-on sentence. + That sentence is acceptable, but adding a comma before "... but we still stayed up ..." would provide a pause and avoid the chance of having it read like a run-on sentence. In a compound sentence that contains several short independent clauses, separate the clauses with commas and use a comma before the conjunction. diff --git a/en-US/R.xml b/en-US/R.xml index 5176aaa..21d275f 100644 --- a/en-US/R.xml +++ b/en-US/R.xml @@ -10,7 +10,7 @@ RAM - Correct. Do not use "Ram" or any other variations. It is an acronym for "random access memory." + Correct. Do not use "Ram" or any other variations. It is an acronym for "random access memory". @@ -20,7 +20,7 @@ RAM disk - Correct. Do not use "RAMdisk," "ramdisk," or "RAdisk." + Correct. Do not use "RAMdisk", "ramdisk", or "RAdisk". Refers to RAM that is configured to simulate a disk drive. You can access files on a RAM disk as you would access files on a real disk. RAM disks, however, are approximately a thousand times faster than hard disk drives. They are particularly useful, therefore, for applications that require frequent disk accesses. @@ -95,7 +95,7 @@ reboot - Correct. Do not use "re-boot." + Correct. Do not use "re-boot". @@ -105,7 +105,7 @@ RedBoot - Correct. Do not use "Redboot" or "Red Boot." + Correct. Do not use "Redboot" or "Red Boot". @@ -115,7 +115,7 @@ refer to - Do not use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source). Use "See." + Do not use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source). Use "See". @@ -165,7 +165,7 @@ right-click - v. Write the term hyphenated. Do not use "right click." + v. Write the term hyphenated. Do not use "right click". @@ -211,7 +211,7 @@ RPM - Initialism for RPM Package Manager. RPM manages files in the RPM format, known as RPM packages. Note: RPM packages are known informally as rpm files, but this informal usage is not used in Red Hat documentation, to avoid confusion with the command name. Files in RPM format are referred to as "RPM packages." + Initialism for RPM Package Manager. RPM manages files in the RPM format, known as RPM packages. Note: RPM packages are known informally as rpm files, but this informal usage is not used in Red Hat documentation, to avoid confusion with the command name. Files in RPM format are referred to as "RPM packages". @@ -221,7 +221,7 @@ runlevel - Correct. Do not use "run level" or "run-level." + Correct. Do not use "run level" or "run-level". diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml index a02e99a..7c735c6 100644 --- a/en-US/Revision_History.xml +++ b/en-US/Revision_History.xml @@ -271,7 +271,7 @@ - Add "cloudbursting," "cloudwashing," and "pluggable" to usage dictionary. + Add "cloudbursting", "cloudwashing", and "pluggable" to usage dictionary. @@ -414,7 +414,7 @@ BZs 871652, 820071, 821611, 821610. Updates to and integration of Chapters X, Y, and Z. - Updated section on "Avoiding Slang." + Updated section on "Avoiding Slang". Removed some redundant entries. Various cleanups based on IBM Style Guide. New entries from Word Nerds discussions. diff --git a/en-US/S.xml b/en-US/S.xml index fabaee0..c2b66bf 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -10,7 +10,7 @@ S/390 - Use the full description "IBM S/390." Do not use "s390," "S390," or any other variations. + Use the full description "IBM S/390". Do not use "s390", "S390", or any other variations. @@ -20,7 +20,7 @@ SaaS - The correct abbreviation for "Software-as-a-Service." + The correct abbreviation for "Software-as-a-Service". See also . @@ -31,7 +31,7 @@ Samba - Correct. Do not use "samba" or "SAMBA." + Correct. Do not use "samba" or "SAMBA". @@ -41,7 +41,7 @@ S-record - Correct. Do not use "s-record," "Record," "s-Record," or any other variations. + Correct. Do not use "s-record", "Record", "s-Record", or any other variations. @@ -51,7 +51,7 @@ screen capture - n. Do not use "screen shot," "screenshot," or other terms or variations. See the relevant entry in the IBM Style Guide. + n. Do not use "screen shot", "screenshot", or other terms or variations. See the relevant entry in the IBM Style Guide. @@ -61,7 +61,7 @@ screen saver - n. Do not use "screensaver." + n. Do not use "screensaver". @@ -71,7 +71,7 @@ scrollbar - n. Do not use "scroll bar" or "scroll-bar." + n. Do not use "scroll bar" or "scroll-bar". @@ -151,7 +151,7 @@ send out - Do not use. Instead, use "emit" or "issue." + Do not use. Instead, use "emit" or "issue". @@ -216,7 +216,7 @@ Pronounced "shä" and thus requires "an" as the indefinite article. - SHA stands for Secure Hash Algorithm; each is a cryptographic hash function. SHA2 variants are often specified by using their digest size, in bits, as the trailing number, in lieu of "2." Thus "SHA224," "SHA256," "SHA384," and "SHA512" are considered correct when referring to these specific hash functions. + SHA stands for Secure Hash Algorithm; each is a cryptographic hash function. SHA2 variants are often specified by using their digest size, in bits, as the trailing number, in lieu of "2". Thus "SHA224", "SHA256", "SHA384", and "SHA512" are considered correct when referring to these specific hash functions. See for full details. @@ -229,7 +229,7 @@ Shadowman - Correct. Do not use "Shadow Man" or "ShadowMan." The Red Hat Shadowman logo is a trademark of Red Hat, Inc., registered in the United States and other countries. + Correct. Do not use "Shadow Man" or "ShadowMan". The Red Hat Shadowman logo is a trademark of Red Hat, Inc., registered in the United States and other countries. @@ -292,7 +292,7 @@ shell prompt - Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use "command prompt," "terminal," or "shell." + Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use "command prompt", "terminal", or "shell". @@ -312,7 +312,7 @@ shut down - v. Correct. Do not use "shut-down." Only use "shutdown" when referring to the /sbin/shutdown system command. + v. Correct. Do not use "shut-down". Only use "shutdown" when referring to the /sbin/shutdown system command. @@ -423,7 +423,7 @@ SOCKS - Correct. Do not use "socks." When specifying a SOCKS version, use "SOCKSv4" or "SOCKSv5." + Correct. Do not use "socks". When specifying a SOCKS version, use "SOCKSv4" or "SOCKSv5". @@ -433,7 +433,7 @@ softcopy - Do not use. Instead, use "online." For example, "To view the online documentation ..." + Do not use. Instead, use "online". For example, "To view the online documentation ...". @@ -443,7 +443,7 @@ sound card - n. Do not use "soundcard" or "sound-card." + n. Do not use "soundcard" or "sound-card". @@ -453,7 +453,7 @@ Source-Navigator™ - Correct. Do not use "Source Navigator." Source-Navigator™ is a trademark of Red Hat. + Correct. Do not use "Source Navigator". Source-Navigator™ is a trademark of Red Hat. @@ -492,7 +492,7 @@ a programming and technical sense, it also means "Run the sourcespec file - n. Use to refer to an RPM spec file. Do not use "specfile." + n. Use to refer to an RPM spec file. Do not use "specfile". @@ -502,7 +502,7 @@ a programming and technical sense, it also means "Run the sourcespecific - When used as a modifier, put a hyphen before "specific," such as "MIP-specific," "Linux-specific," and "chip-specific." + When used as a modifier, put a hyphen before "specific", such as "MIP-specific", "Linux-specific", and "chip-specific". @@ -512,10 +512,10 @@ a programming and technical sense, it also means "Run the sourcespelled - Correct. It is the standard US English spelling. Do not use "spelt." + Correct. It is the standard US English spelling. Do not use "spelt". @@ -528,13 +528,13 @@ a programming and technical sense, it also means "Run the source - When referring to Microsoft's proprietary product, SQL Server, pronounce it as a word: "sequel." In this case, it takes "a" as an indefinite article. + When referring to Microsoft's proprietary product, SQL Server, pronounce it as a word: "sequel". In this case, it takes "a" as an indefinite article. - Note: Oracle also pronounces its SQL-based products (such as PL/SQL) as "sequel." + Note: Oracle also pronounces its SQL-based products (such as PL/SQL) as "sequel". - More generally, avoid use of "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL." When discussing Microsoft SQL Server, write "Microsoft SQL Server." When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL." + More generally, avoid use of "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL". When discussing Microsoft SQL Server, write "Microsoft SQL Server". When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL". @@ -554,7 +554,7 @@ a programming and technical sense, it also means "Run the sourceSSH - Initialism for Secure Shell, a network protocol for data exchange with a secure channel. When referring to the protocol, do not use "ssh," "Ssh," or other variants. When referring to the command, use ssh. + Initialism for Secure Shell, a network protocol for data exchange with a secure channel. When referring to the protocol, do not use "ssh", "Ssh", or other variants. When referring to the command, use ssh. Do not use as a verb. @@ -564,10 +564,10 @@ a programming and technical sense, it also means "Run the source - Incorrect: To begin, "ssh to the remote server." + Incorrect: To begin, "ssh to the remote server". - Correct: "Use SSH to connect to the remote server," "Open an SSH connection," or something similar. + Correct: "Use SSH to connect to the remote server", "Open an SSH connection", or something similar. @@ -587,7 +587,7 @@ a programming and technical sense, it also means "Run the sourcestand-alone - adj. Write hyphenated. Do not use "standalone." + adj. Write hyphenated. Do not use "standalone". Refers to something that is self-contained, or that does not require any other devices to function. @@ -603,7 +603,7 @@ a programming and technical sense, it also means "Run the sourceStarOffice - A legacy Linux desktop suite. Do not use "Star," "Staroffice," or "Star Office." + A legacy Linux desktop suite. Do not use "Star", "Staroffice", or "Star Office". @@ -617,7 +617,7 @@ a programming and technical sense, it also means "Run the sourcestart up - v. Do not use. Instead, use "activate" or "invoke." + v. Do not use. Instead, use "activate" or "invoke". @@ -637,7 +637,7 @@ a programming and technical sense, it also means "Run the sourcestraightforward - adj., adv. Accepted references prescribe the use of the one-word form in all cases. Do not use "straight-forward." + adj., adv. Accepted references prescribe the use of the one-word form in all cases. Do not use "straight-forward". @@ -657,7 +657,7 @@ a programming and technical sense, it also means "Run the sourcesubcommand - Correct. Do not use "sub-command" or refer to a subcommand as a "verb." + Correct. Do not use "sub-command" or refer to a subcommand as a "verb". A subcommand refers to a secondary or even a tertiary command that is used with a primary command. Not to be confused with options or arguments, subcommands operate on ever more focused objects or entities. For example: @@ -676,7 +676,7 @@ a programming and technical sense, it also means "Run the sourcesubdirectory - Correct. Do not use "sub-directory." See also . + Correct. Do not use "sub-directory". See also . @@ -686,7 +686,7 @@ a programming and technical sense, it also means "Run the sourcesubmenu - Correct. Do not use "sub-menu." See also . + Correct. Do not use "sub-menu". See also . @@ -696,10 +696,10 @@ a programming and technical sense, it also means "Run the sourcesubpackage - Correct. Do not use "sub-package." + Correct. Do not use "sub-package". - This word has a specific, specialized meaning in Red Hat products. An RPM spec file can define more than one package: these additional packages are called "subpackages." + This word has a specific, specialized meaning in Red Hat products. An RPM spec file can define more than one package: these additional packages are called "subpackages". Any other use of this word is strongly discouraged. @@ -715,7 +715,7 @@ a programming and technical sense, it also means "Run the sourcesuperuser - A synonym for the root user. More common in Solaris documentation than Linux. If and when used, this spelling is correct. Do not use "super user" or "super-user." + A synonym for the root user. More common in Solaris documentation than Linux. If and when used, this spelling is correct. Do not use "super user" or "super-user". @@ -725,7 +725,7 @@ a programming and technical sense, it also means "Run the sourceswap space - Correct. Do not use "swapspace." Capitalize at the beginning of a sentence only. + Correct. Do not use "swapspace". Capitalize at the beginning of a sentence only. @@ -735,7 +735,7 @@ a programming and technical sense, it also means "Run the sourceSybase Adaptive Server Enterprise (ASE) - Use SAP Sybase Adaptive Server Enterprise (ASE) in the first instance. Subsequent entries can use the abbreviation "Sybase ASE." If discussing the high-availability version, use "Sybase ASE and High Availability." + Use SAP Sybase Adaptive Server Enterprise (ASE) in the first instance. Subsequent entries can use the abbreviation "Sybase ASE". If discussing the high-availability version, use "Sybase ASE and High Availability". See http://www.sybase.com/products/databasemanagement/adaptiveserverenterprise for more information. diff --git a/en-US/T.xml b/en-US/T.xml index 159c5f3..0d2b5b3 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -10,7 +10,7 @@ taskbar - n. One word. Do not use "task bar." + n. One word. Do not use "task bar". @@ -30,7 +30,7 @@ telco - Preferred abbreviation for "telecommunications company." Do not use "telecom." See also . + Preferred abbreviation for "telecommunications company". Do not use "telecom". See also . Use "telecommunications service provider" on first use. Subsequent uses can be "telco" or "telco service provider"; only use "telco" when the context makes it clear that the industry is engaged in providing telecommunications services. Use in URLs. @@ -54,7 +54,7 @@ telecommunications - Vertical for communication service providers. Preferred abbreviation is "telco." + Vertical for communication service providers. Preferred abbreviation is "telco". @@ -90,7 +90,7 @@ text-based - adj. Correct. Do not use "text based." + adj. Correct. Do not use "text based". @@ -100,7 +100,7 @@ text mode - Correct. Do not use "textmode" or "text-mode." + Correct. Do not use "textmode" or "text-mode". A video mode in which a display screen is divided into rows and columns of boxes. Each box can contain one character. Text mode is also called character mode. @@ -154,7 +154,7 @@ time frame (n.) - Correct. Do not use "timeframe" or "time-frame." + Correct. Do not use "timeframe" or "time-frame". @@ -164,7 +164,7 @@ time zone (n.) - Correct. Do not use "timezone" or "time-zone." + Correct. Do not use "timezone" or "time-zone". @@ -185,7 +185,7 @@ toolbar (n.) - Correct. Do not use "tool bar" or "tool-bar." + Correct. Do not use "tool bar" or "tool-bar". @@ -205,7 +205,7 @@ totally - Do not use. See "basically." + Do not use. See "basically". @@ -215,7 +215,7 @@ troubleshoot (v.) - Correct. Do not use "trouble shoot" or "trouble-shoot." + Correct. Do not use "trouble shoot" or "trouble-shoot". diff --git a/en-US/U.xml b/en-US/U.xml index 76b94be..5e4f2a9 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -20,7 +20,7 @@ UltraSPARC - Correct. Do not use "ULTRASPARC," "UltraSparc," or other variations. + Correct. Do not use "ULTRASPARC", "UltraSparc", or other variations. UltraSPARC is a trademark of SPARC International, Inc., and is used under license by Sun Microsystems, Inc. Products that bear the SPARC trademarks are based on an architecture developed by Sun Microsystems, Inc. @@ -43,7 +43,7 @@ uninterruptible - adj. Despite not appearing in the American Heritage Dictionary, this term does appear in the Merriam-Webster Unabridged Dictionary, and is considered acceptable in Red Hat documentation, especially in the context of "uninterruptible power supply (UPS)." + adj. Despite not appearing in the American Heritage Dictionary, this term does appear in the Merriam-Webster Unabridged Dictionary, and is considered acceptable in Red Hat documentation, especially in the context of "uninterruptible power supply (UPS)". @@ -53,13 +53,13 @@ UNIX - Correct. Do not use "Unix" or "unix." + Correct. Do not use "Unix" or "unix". UNIX is a registered trademark of The Open Group. - Do not use "UNIX-like." Use an expression such as "Linux, UNIX, and similar operating systems" instead. + Do not use "UNIX-like". Use an expression such as "Linux, UNIX, and similar operating systems" instead. @@ -95,7 +95,7 @@ upgrade - v. Correct. Do not use "up-grade" or "up grade." + v. Correct. Do not use "up-grade" or "up grade". @@ -135,7 +135,7 @@ upstream - Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "up-stream" or "up stream." + Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "up-stream" or "up stream". @@ -145,7 +145,7 @@ uptime - n. Correct. Do not use "up-time" or "up time." + n. Correct. Do not use "up-time" or "up time". @@ -169,7 +169,7 @@ user - n. When referring to the reader, use "you" instead of "the user." For example, "The user must..." is incorrect. Use "You must..." instead. + n. When referring to the reader, use "you" instead of "the user". For example, "The user must ..." is incorrect. Use "You must ..." instead. If referring to more than one user, calling the collection "users" is acceptable, such as "Other users might want to access your database." @@ -182,7 +182,7 @@ user interface - n. Correct. Do not use "user-interface" or "userinterface." + n. Correct. Do not use "user-interface" or "userinterface". The junction between a user and a computer program. An interface is a set of commands or menus through which a user communicates with a program. In a command-driven interface, you enter commands. In a menu-driven interface, you select command choices from various menus that are displayed on the screen. @@ -207,7 +207,7 @@ user space - n. Correct when used as a noun. When used as a modifier, use the hyphenated form, "user-space." Do not use "userspace." + n. Correct when used as a noun. When used as a modifier, use the hyphenated form, "user-space". Do not use "userspace". diff --git a/en-US/V.xml b/en-US/V.xml index f10df65..e57e6f5 100644 --- a/en-US/V.xml +++ b/en-US/V.xml @@ -40,7 +40,7 @@ video mode - Correct. Do not use "video-mode" or "videomode." + Correct. Do not use "video-mode" or "videomode". The setting of a video adapter. Most video adapters can run in either text mode or graphics mode. In text mode, a monitor can display only ASCII characters. In graphics mode, a monitor can display any bit-mapped image. In addition to the text and graphics modes, video adapters offer different modes of resolution and color depth. @@ -81,10 +81,10 @@ virtualized guest - The term "virtualized guest" should be used only when comparing a "fully virtualized guest" with a "paravirtualized guest." + The term "virtualized guest" should be used only when comparing a "fully virtualized guest" with a "paravirtualized guest". - See also "guest operating system." + See also "guest operating system". @@ -97,7 +97,7 @@ Refers to virtual hardware that consists of virtual CPUs, memory, devices, and so on. Do not use "guest virtual machine" except for specific emphasis that it is a guest. - It can be abbreviated to "VM" provided that the term is first introduced in the same content in its full version, and without any possible confusion with other terms, such as "virtual memory." Author discretion is recommended. + It can be abbreviated to "VM" provided that the term is first introduced in the same content in its full version, and without any possible confusion with other terms, such as "virtual memory". Author discretion is recommended. diff --git a/en-US/W.xml b/en-US/W.xml index 99d767b..136935a 100644 --- a/en-US/W.xml +++ b/en-US/W.xml @@ -26,9 +26,9 @@ want - Use instead of "wish" or "would like." + Use instead of "wish" or "would like". Rephrase to avoid whenever possible. - For example, "If you want to use the debugger, ..." can be rewritten as "To use the debugger, ..." + For example, "If you want to use the debugger, ..." can be rewritten as "To use the debugger, ...". @@ -38,10 +38,10 @@ WCA - An abbreviation of "web clipping application," to extract static information from a web server and load that data onto a web-enabled personal digital assistant (PDA). + An abbreviation of "web clipping application", to extract static information from a web server and load that data onto a web-enabled personal digital assistant (PDA). - WCAs are also called "query applications." + WCAs are also called "query applications". @@ -85,8 +85,8 @@ Do not use. - Use a more direct construction, or use "recommend." - For example, instead of "We suggest that you make a backup of your data disk," write "Back up your data disk." + Use a more direct construction, or use "recommend". + For example, instead of "We suggest that you make a backup of your data disk", write "Back up your data disk". diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index d560434..8ce468a 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -80,7 +80,7 @@ you - Use second person wherever possible. Do not use "I," "we," "he," or "she." + Use second person wherever possible. Do not use "I", "we", "he", or "she." @@ -124,7 +124,7 @@ zSeries - "IBM System z" is correct for the first reference in a manual; use "System z" for subsequent references. Do not use "S/390x," "s390x," "IBM zSeries," or "zSeries." + "IBM System z" is correct for the first reference in a manual; use "System z" for subsequent references. Do not use "S/390x", "s390x", "IBM zSeries", or "zSeries." From 88e9b30361c952c1ce823a8fa45a14ff595d2a90 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 19 Jan 2022 10:44:38 +0000 Subject: [PATCH 24/30] 337 Add guidance about referring to UI elements and other publication titles (#338) * 337 Add guidance about referring to UI elements and other publication titles * 337 Minor punctuation fix --- en-US/Design.xml | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 42f4694..ab20c74 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -15,15 +15,20 @@ Capitalization - The standard for all Red Hat technical documentation is title case for all headings and titles. + 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. - The currently accepted reference for determining title case is at https://titlecase.com/titlecase. - - - Use sentence case for captions, legends, diagram labels, and table column headers. + + + Use title case also when referring to the titles of other publications, even if the title on the publication itself uses different casing. + + + The currently accepted reference for determining title case is at https://titlecase.com/titlecase. + + + Use sentence case for captions, legends, diagram labels, and table column headers. They are not classified as titles. - + Marketing and Brand Capitalization Guide @@ -81,9 +86,14 @@ In all cases, see the IBM Style Guide for initial guidance. The following sections highlight exceptions or cases that might otherwise cause confusion. + + + When writing about items in a user interface (UI), match the capitalization and spelling of those items from the interface. + However, if the interface contains a spelling error, then correct the spelling in your writing, and get the interface corrected if possible. + Depending on the context, an option might be to write around an incorrectly spelled interface item rather than naming it specifically.
- User Interface (UI) Elements, Punctuation, and Symbols + User Interface Elements, Punctuation, and Symbols When describing UI elements, do not include punctuation that appears on those elements, unless omission of that punctuation might lead to confusion. From d8b9538d59a50f4c5b5eb25be5433195193b0f54 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Fri, 21 Jan 2022 09:58:57 +0000 Subject: [PATCH 25/30] 339 Added information for IBM Style online (#340) * 339 Added information for IBM Style online * 339 Add accessing IBM Style Guide online --- en-US/Resources.xml | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/en-US/Resources.xml b/en-US/Resources.xml index dbdc529..cf58ac1 100644 --- a/en-US/Resources.xml +++ b/en-US/Resources.xml @@ -52,6 +52,41 @@ IBM Style Guide. IBM Corporation, latest version. + + Red Hat employees can now access the latest version of the IBM Style Guide online, at https://www.ibm.com/docs/en/ibm-style/. + + + Go to that web page, and click Log in to view content. + + + On the Log in to IBM page, in the IBMid field, enter your xxx@redhat.com email address and click Continue. + + + The IBM Style page shows the following categories: + + + + + What's new + + + + + Word usage + + + + + Inclusive language + + + + + Topics A to Z + + + + @@ -60,9 +95,9 @@ - + - Merriam-Webster Collegiate Dictionary + Merriam-Webster Unabridged Dictionary Visit https://www.merriam-webster.com/ for subscription options. From 6ddc9fe81c75049ec1452adaa56b25ce8f9b26c9 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Mon, 24 Jan 2022 11:55:49 +0000 Subject: [PATCH 26/30] 298 Update 'backend' (#341) * 298 Update 'backend' * 298 Minor wording update --- en-US/B.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en-US/B.xml b/en-US/B.xml index e24ea38..ebfca95 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -7,7 +7,7 @@ B - back end, back-end + back end, back-end, backend n. Two words. Refers to software that performs the final stages of a process, or to tasks that are not visible to the user. For example, "each back end provides a set of calls". @@ -16,7 +16,7 @@ adj. Hyphenate. For example, "when the back-end database processes a search operation …" - Do not use "backend". + Use the one-word form only if it is part of the established product terminology, for example "Mobile Backend-as-a-Service", and when it is not being used to describe a generic process. See also From 23589e61911adb6f9035972c808daef85c7bc925 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 2 Feb 2022 17:12:22 +0000 Subject: [PATCH 27/30] 287 Add release notes (#343) * 287 Add release notes * 287 Minor change to release wording --- en-US/New.xml | 72 +++++++++++++++++++ en-US/O.xml | 2 +- en-US/Preface.xml | 3 + ...le_Conventions_for_Writers_and_Editors.ent | 4 +- ...le_Conventions_for_Writers_and_Editors.xml | 10 +-- 5 files changed, 83 insertions(+), 8 deletions(-) create mode 100644 en-US/New.xml diff --git a/en-US/New.xml b/en-US/New.xml new file mode 100644 index 0000000..9a1a58e --- /dev/null +++ b/en-US/New.xml @@ -0,0 +1,72 @@ + + +%BOOK_ENTITIES; +]> +
+ New in This Release + + Release 5.1 + Minor update in January 2022 to address some reported issues: + + + + Accessing IBM Style online. + + + Updated guidance for long commands. + + + Updated guidance for referring to object names. + + + Updated guidance for non-breaking spaces. + + + Updated guidance for punctuation with quotation marks. + + + The gerund verb form is no longer required in section titles. + + + Pronouncing file or directory names that begin with special characters. + + + Avoid "the product allows the user to do xyz". + + + Avoid consecutive headings. + + + Guidance to refer to UI elements and to other publication titles. + + + Clarification that diagram labels use sentence case. + + + New or updated usage entries: backend, IaC, number sign, on premise/on-premise, prebaked, unset. + + + + + Release 5.0 + Major update in July 2021 to align with some recent changes in IBM Style: + + + + Sentence case is required for captions, legends, and diagram labels. + + + Punctuation: Added sections on referring to punctuation marks and names of punctuation marks and special characters. + + + Rename Chapter 4 to "Choosing Appropriate Language": expand scope beyond slang and jargon, to cover inclusive language; avoiding ambiguities (moved from Chapter 2 and added more categories); dates and times (AM and PM are now written in uppercase without periods); and numbers. + + + Usage A-Z: Various additions and updates. Corrected alphabetical sorting sequence. Moved items that are not literal term entries to an earlier chapter. + + + Minor edits so the guide itself conforms with its own advice. + + +
diff --git a/en-US/O.xml b/en-US/O.xml index 5b05a69..6bffc0d 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -111,7 +111,7 @@ - on premise + on premise, on-premise adverb diff --git a/en-US/Preface.xml b/en-US/Preface.xml index b356255..37932d5 100644 --- a/en-US/Preface.xml +++ b/en-US/Preface.xml @@ -5,6 +5,9 @@ ]> Preface + + + diff --git a/en-US/Style_Conventions_for_Writers_and_Editors.ent b/en-US/Style_Conventions_for_Writers_and_Editors.ent index 87f791a..a9587a6 100644 --- a/en-US/Style_Conventions_for_Writers_and_Editors.ent +++ b/en-US/Style_Conventions_for_Writers_and_Editors.ent @@ -1,5 +1,5 @@ - + - \ No newline at end of file + \ No newline at end of file diff --git a/en-US/Style_Conventions_for_Writers_and_Editors.xml b/en-US/Style_Conventions_for_Writers_and_Editors.xml index 012de66..8c5b4b0 100644 --- a/en-US/Style_Conventions_for_Writers_and_Editors.xml +++ b/en-US/Style_Conventions_for_Writers_and_Editors.xml @@ -59,15 +59,15 @@ - + From 79ab362656ef570b22ffa9336d00609c08272bb5 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 3 Feb 2022 11:30:41 +0000 Subject: [PATCH 28/30] 344 Update chapter 4 ID --- en-US/F.xml | 2 +- en-US/Language.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/en-US/F.xml b/en-US/F.xml index 94f6486..9636404 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -319,7 +319,7 @@ fuzzy - Correct only when referring to fuzzy searches. See for details and examples. + Correct only when referring to fuzzy searches. See for details and examples. diff --git a/en-US/Language.xml b/en-US/Language.xml index 5ce9a32..1cce2b9 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -3,7 +3,7 @@ %BOOK_ENTITIES; ]> - + Choosing Appropriate Language From 17e0e7ec414e3ba90799aab87a72484808467a3e Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 4 Feb 2022 11:38:04 +0000 Subject: [PATCH 29/30] 348 Fix to triplicate headings --- en-US/Language.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/en-US/Language.xml b/en-US/Language.xml index 5ce9a32..2ea10c9 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1074,7 +1074,7 @@ Numbers (move from N entry) --> - Verb phrases + Infinitives When you have more than one infinitive verb within a sentence, be clear what each verb refers to. @@ -1147,7 +1147,7 @@ Numbers (move from N entry) --> - Verb phrases + Pronouns Avoid ambiguous pronoun references, where a pronoun can refer to more than one antecedent. @@ -1196,7 +1196,7 @@ Numbers (move from N entry) --> - Use of "using" + Use of "Using" Use of the word "using" can result in ambiguity, which can often be resolved by using "that uses" or "by using", according to the meaning. @@ -1244,7 +1244,7 @@ Numbers (move from N entry) --> - Verb phrases + Verb Phrases Ensure that a verb phrase at the start of a sentence modifies the correct word. From 01ac8814302432cc46abdcf79b1242aa7c0b27d6 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 4 Feb 2022 17:05:23 +0000 Subject: [PATCH 30/30] 348 Update release number --- en-US/Book_Info.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index 06528e6..2d513ce 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -8,7 +8,7 @@ Red Hat Technical Writing Style Guide - 5.0 + 5.1 1