diff --git a/en-US/A.xml b/en-US/A.xml index 72791ed..044cebd 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -14,6 +14,44 @@ + + + AArch64, aarch64 + + + n. A 64-bit version of the ARM architecture. + Use this term when referring to operating systems and server instances, for example Red Hat Enterprise Linux, Fedora, CoreOS, and other Linux distributions. + + + Use the uppercase (AArch64) format in general cases when referring to system architecture. + Use the lowercase (aarch64) format only when referring to objects or parameters. + It can be styled as code (monospace font or a code-styled block) when referring to code. + + + Cloud providers might use different formats of this term to refer to architectures. + If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case. + + + Examples: + + + + + When running Red Hat Enterprise Linux with an AArch64 system, run the following commands: + + + + + Specify the system architecture of your cluster, such as x86_64 or aarch64. + + + + + Refer also to , , , , , and . + + + + above @@ -102,44 +140,6 @@ - - - AArch64, aarch64 - - - n. A 64-bit version of the ARM architecture. - Use this term when referring to operating systems and server instances, for example Red Hat Enterprise Linux, Fedora, CoreOS, and other Linux distributions. - - - Use the uppercase (AArch64) format in general cases when referring to system architecture. - Use the lowercase (aarch64) format only when referring to objects or parameters. - It can be styled as code (monospace font or a code-styled block) when referring to code. - - - Cloud providers might use different formats of this term to refer to architectures. - If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case. - - - Examples: - - - - - When running Red Hat Enterprise Linux with an AArch64 system, run the following commands: - - - - - Specify the system architecture of your cluster, such as x86_64 or aarch64. - - - - - Refer also to , , , , , and . - - - - AMD64, amd64 @@ -299,24 +299,21 @@ - - as well as + + artificial intelligence (AI) - Not interchangeable with "and". - "As well as" used in a series places more emphasis on the items preceding it, whereas "and" places equal weight on all items in the series. - For example, "We sell kitchen electronics and china, as well as some gourmet foods." - But "We sell kitchen electronics, china, and silverware." + Unless clarity requires it or the concept is being introduced or explained, "artificial intelligence" does not have to be spelled out on first use; "AI" is understood and suffices. When spelling it out, do not capitalize the term. - as-a-Service + as-a-Service - Some as-a-Service acronyms overlap. + Some "as-a-Service" acronyms overlap. To avoid confusion, always spell out the full term on first use. @@ -412,7 +409,43 @@ - + + + as Code + + + Use camel case for both the full term and the acronym. + Do not hyphenate. + Some "as Code" acronyms might overlap. + To avoid confusion, always spell out the full term on first use. + + + Examples: + + + + + Configuration as Code (CaC) + + + + + + Infrastructure as Code (IaC) + + + + + + Policy as Code (PaC) + + + + + + + + as long as @@ -423,6 +456,19 @@ + + + as well as + + + Not interchangeable with "and". + "As well as" used in a series places more emphasis on the items preceding it, whereas "and" places equal weight on all items in the series. + For example, "We sell kitchen electronics and china, as well as some gourmet foods." + But "We sell kitchen electronics, china, and silverware." + + + + ATM diff --git a/en-US/B.xml b/en-US/B.xml index c09cfd3..db17543 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -24,6 +24,15 @@ + + + backtrace + + + n. "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback", possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. + + + backup, back up @@ -59,15 +68,6 @@ - - - backtrace - - - n. "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback", possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. - - - backwards compatible diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index 6371a85..148be76 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -8,7 +8,7 @@ Red Hat Technical Writing Style Guide - 7.0 + 7.1 1 diff --git a/en-US/C.xml b/en-US/C.xml index 4084c54..478d972 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -248,6 +248,17 @@ + + code base + + + n. Two words. + Do not use "codebase", outside the specific context of codebase.com. + + + + + colocate, colocation @@ -388,16 +399,7 @@ - - Containers-as-a-Service - - - The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. Refer also to . - - - - container-based @@ -417,6 +419,16 @@ + + + Containers-as-a-Service + + + The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. Refer also to . + + + + continuous delivery (CD) diff --git a/en-US/D.xml b/en-US/D.xml index bb8f48e..adbd557 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -218,23 +218,23 @@ Describe, rather than label. - - Disk Druid + + disk, disc - Correct. Do not use "Disk druid", "disk druid", or "diskdruid". This is a partitioning tool that is incorporated into Red Hat Enterprise Linux. + Use "compact disc" or "hard disk". + - - disk, disc + + Disk Druid - Use "compact disc" or "hard disk". + Correct. Do not use "Disk druid", "disk druid", or "diskdruid". This is a partitioning tool that is incorporated into Red Hat Enterprise Linux. - diff --git a/en-US/Design.xml b/en-US/Design.xml index d56e377..7411bd1 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -501,7 +501,8 @@ $ vi myFile.txt --> - You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required. + Do not use manual line indentation for the second and subsequent lines of commands. + For some output formats, no control is possible over where lines would break, and any indentation might appear as extra spaces in inelegant places. @@ -1001,6 +1002,7 @@ telemetry-operator.v1.0.0 Telemetry Operator ... --> However, in some cases, the sentence might be easier to understand if the noun appears first, or if additional language separates the object name from the noun. For example, if the noun refers to a password, a value, or a status, then consider stating the noun first, or including explanatory language between the object name and the noun, or doing both. + In other cases, a noun might be omitted. @@ -1027,6 +1029,83 @@ telemetry-operator.v1.0.0 Telemetry Operator ... --> Define the backup_tmp variable with a value of /tmp in the defaults/main.yml file. + + The is:clear key is set to the false value. + The is:clear key is set to false. + + + + + + + +
+ + +
+ Naming of Object Classes + + When naming an object, consider the impact of its name when writing about the object. + Avoid duplication, alliteration, or long names. + In cases where including the class in an object name helps to provide clarity, avoid including the object's class in the last part of its name. + This approach avoids repetition when writing about the object where the noun that follows the object name indicates its class. + + + + + + + + + + Example + Improvement + + + + + + + + The user that you use to log in is the remote-user user. + Log in as the user-remote user. + + + + Go to the local-project project. + Go to the proj-local project. + + + + Use the base-layer layer of the container. + Use the base-image layer of the container. + + + + Create the instance in the prod-environment environment. + Create the instance in the prod environment. + + + + + Use the oc process --parameters command to view the parameter of the roster-template template. + Use the oc process --parameters command to view the parameter of the roster template. + + + + Create the namesList variable in the my-file file as part of the managedCluster cluster. + Create the namesList variable in the file-test file as part of the cluster-managed cluster. + + + + Verify that the famous-quotes-pvc PVC (Persistent Volume Claim) is successfully created. + Verify that the famous-quotes PVC (Persistent Volume Claim) is successfully created. + + diff --git a/en-US/E.xml b/en-US/E.xml index bf7cb4f..7948e7a 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -6,6 +6,17 @@ E + + earlier + + + Use to refer to earlier releases of products. Do not use "older" or related terms. + Refer also to . + + + + + ebook, e-commerce, e-learning, email @@ -15,22 +26,21 @@ - - e.g. + + edge - Red Hat technical documentation always expands these abbreviations. Write out "for example". + Describes network elements outside the gateway and server-side or cloud-side functions (for example, "an edge device"). + Do not refer to "the edge" without qualifying it; define the first instance (for example, "the edge of the network"). - - - earlier + + e.g. - Use to refer to earlier releases of products. Do not use "older" or related terms. - Refer also to . + Red Hat technical documentation always expands these abbreviations. Write out "for example". diff --git a/en-US/G.xml b/en-US/G.xml index 9faef8e..9cf59ac 100644 --- a/en-US/G.xml +++ b/en-US/G.xml @@ -102,6 +102,20 @@ + + + generative AI, gen AI + + + Unless clarity requires it or the concept is being introduced or explained, "generative artificial intelligence" does not have to be spelled out on first use; the abbreviation "gen AI" is understood and suffices. + When spelling it out, do not capitalize the term. + + + Note: Because generative AI is a relatively new technology concept, the term and how it is applied is evolving, so this guidance might change accordingly. + + + + GEO, geo diff --git a/en-US/I.xml b/en-US/I.xml index a9ec824..881a55b 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -25,16 +25,6 @@ - - - Infrastructure as Code (IaC) - - - Based on search volume, the nonhyphenated full term and camel-case acronym are preferred. Use uppercase "I" and "C". - - - - IBM Z @@ -96,6 +86,16 @@ + + + Infrastructure as Code (IaC) + + + Based on search volume, the nonhyphenated full term and camel-case acronym are preferred. Use uppercase "I" and "C". + + + + inline diff --git a/en-US/L.xml b/en-US/L.xml index 0b14e96..165ced1 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -222,6 +222,15 @@ + + + log out of + + + v. Write as three words. Use "log out of", not "log out from". For example, "to log out of the system". + + + look at diff --git a/en-US/Language.xml b/en-US/Language.xml index f27ce62..ac8a695 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -943,9 +943,26 @@ +
+ Use of "Allow" - Avoid stating that a product or feature allows the user to do something. Focus instead on what the user does. + Except when referring specifically to permission, avoid stating that a product or feature allows the user to do something. + + + Valid Uses of "Allow" to Refer to Permission + + + Some open source licenses allow code to be reused in proprietary products. + + + You can configure the sudo command to allow specific users to run any command as some other user. + + + + In cases that do not refer to permission, whenever possible, focus instead on what the user, service, or agent does, or replace "allow" with a different verb, such as "enable". + +
@@ -970,6 +987,21 @@ You can use collections to separate core Ansible code updates from updates to modules and plug-ins. + + The system menu allows you to switch network and VPN connections on or off. + From the system menu, you can switch network and VPN connections on or off. + + + + The workspace selector displays active workspaces and allows you to switch between workspaces. + The workspace selector displays active workspaces and enables you to switch between workspaces. + + + @@ -980,6 +1012,8 @@ Report an issue + +
diff --git a/en-US/New.xml b/en-US/New.xml index 1e7fa81..0e40fb1 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -5,6 +5,73 @@ ]>
New in This Release + + Release 7.1 + Maintenance release in June 2025, with some added and updated guidance. + + + + Added an entry for "artificial intelligence (AI)". + Refer to . + + + Added an entry for "as Code". + Refer to . + + + Added an entry for "code base", to use in preference to "codebase". + Refer to . + + + Added an entry for "edge". + Refer to . + + + Added an entry for "generative AI, gen AI". + Refer to . + + + Added an entry for "log out of", to use in preference to "log out from". + Refer to . + + + Added an entry for "print queue", to use in preference to "printer queue". + Refer to . + + + Changed guidance to not use manual line indentation for the second and subsequent lines of commands. + Refer to . + + + Added guidance on the use of "allow". + Refer to . + + + Added guidance on the naming of object classes. + Refer to . + + + Added the dollar sign to the table of punctuation marks and special characters. + Refer to . + + + Changed to use hyphenation for "greater-than" and "less-than", to refer to these characters. + Refer to . + + + Updated guidance to not require a noun with object names in all cases. + Refer to . + + + Updated guidance about the number of items in a bulleted list to allow fewer items in specific cases. + Refer to . + + + Various other fixes. + + + + Release 7.0 Major update in November 2024, with extensive added and updated guidance. @@ -84,9 +151,6 @@ Various other fixes. - - - @@ -104,7 +168,7 @@ Updated guidance about referring to special characters. - Refer to . + Refer to . You can use the possessive form of the company name (Red Hat's) to refer to the company itself, not to any products or services. diff --git a/en-US/P.xml b/en-US/P.xml index 9d1c4cf..3c89e9e 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -208,6 +208,16 @@ + + + print queue + + + n. Use "print queue", not "printer queue", to refer to a list of print jobs that are sent to a printer. + + + + proof of concept diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index bb62e9d..38068ca 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -559,26 +559,45 @@ PLAY [Gather and display facts for managed nodes] **************************** Correct Examples of the Use of Punctuation with Quotation Marks - - For bind mounts, add "bind" and set fstype to "none". - - - Login successful. - ...output omitted... - Using project "default". - - - As in the previous image, the title of the web page is "OpenShift 3 Etherpad". - - - In the program segment, ensure that the value is X'FF'. - - - - Julius Caesar said, "I came. I saw. I conquered." - + + + + + For bind mounts, add "bind" and set fstype to "none". + + + + + + +Login successful. +...output omitted... +Using project "default". + + + + + + + The title of the web page is "OpenShift 3 Etherpad". + + + + + + In the program segment, ensure that the value is X'FF'. + + + + + + Julius Caesar said, "I came. I saw. I conquered." + + + + + +
@@ -752,7 +771,7 @@ PLAY [Gather and display facts for managed nodes] **************************** -
+
Referring to Punctuation Marks and Special Characters To refer to a punctuation mark or special character, use its name alone if it is one of the following standard characters: @@ -762,7 +781,7 @@ PLAY [Gather and display facts for managed nodes] **************************** For all other characters, use the character name followed by the symbol in parentheses. - For special character names that include a noun such as "sign", "symbol", or "character", provide the character name, the noun that describes the symbol, and then the symbol in parentheses, for example "the greater than symbol (>)". + For special character names that include a noun such as "sign", "symbol", or "character", provide the character name, the noun that describes the symbol, and then the symbol in parentheses, for example "the greater-than symbol (>)". For special character names that do not include such nouns, provide the character name and the symbol in parentheses, for example "a forward slash (/)". You can end a sentence with the symbol in parentheses. @@ -781,7 +800,7 @@ PLAY [Gather and display facts for managed nodes] ****************************Referring to Special Characters - When a regular user starts a shell, the prompt includes an ending dollar character ($). + When a regular user starts a shell, the prompt includes an ending dollar sign ($). Use the pipe character (|) to send the output of one program to the input of another program. @@ -885,6 +904,11 @@ PLAY [Gather and display facts for managed nodes] **************************** , Comma + + + $ + Dollar sign + " or “ ” @@ -923,7 +947,7 @@ PLAY [Gather and display facts for managed nodes] **************************** > - Greater than symbol + Greater-than symbol @@ -933,7 +957,7 @@ PLAY [Gather and display facts for managed nodes] **************************** < - Less than symbol + Less-than symbol diff --git a/en-US/S.xml b/en-US/S.xml index fc87234..38e3f54 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -546,6 +546,15 @@ + + source + + + v. In addition to the generic use of this term as a noun and verb, in +a programming and technical sense, it also means "Run the source command against the named file." + + + Source-Navigator™ @@ -556,15 +565,6 @@ - - source - - - v. In addition to the generic use of this term as a noun and verb, in -a programming and technical sense, it also means "Run the source command against the named file." - - - space diff --git a/en-US/Style_Conventions_for_Writers_and_Editors.ent b/en-US/Style_Conventions_for_Writers_and_Editors.ent index 6f5d777..6320711 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/Translation.xml b/en-US/Translation.xml index 1637373..c7c170e 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -31,7 +31,9 @@ Bulleted lists - Use this list type for three or more entries where order is not important. + Use this list type when the order of items is not important. + In most cases, a bulleted list should have three or more entries. + In limited cases, specific publications might choose instead to allow fewer entries in a list. Titles are optional. @@ -87,7 +89,7 @@ Nested lists. - Nested lists themselves can use the attribute if they fall outside the bounds of these recommendations. + Nested list items themselves can use the attribute if they fall outside the bounds of these recommendations.