diff --git a/README.md b/README.md index f07ab67..85a0d78 100644 --- a/README.md +++ b/README.md @@ -8,3 +8,19 @@ The Red Hat Style Guide and Word Usage Dictionary is a joint effort by vari 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. It is based on The IBM Style Guide but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions. + +Dependencies: + +``` +$ sudo dnf install publican +``` + +Also, follow the instructions at https://github.com/RedHatTraining/redhat-styleguide-xsl (access for Red Hat only) to build `publican-brand-redhat-*.noarch.rpm` and install that. + +To build: + +``` +$ publican build --langs=en-US --formats html +``` + +Generates `tmp/en-US/html/index.html`. diff --git a/build b/build new file mode 100755 index 0000000..b2efd20 --- /dev/null +++ b/build @@ -0,0 +1,3 @@ +#!/bin/sh + +publican build --langs en-US --formats html diff --git a/en-US/0-9.xml b/en-US/0-9.xml index 1ad984c..e2d62cb 100644 --- a/en-US/0-9.xml +++ b/en-US/0-9.xml @@ -21,7 +21,7 @@ 2-track (IT) - adj. A less common way to refer to bimodal or hybrid IT. See . + adj. A less common way to refer to bimodal or hybrid IT. Refer to . @@ -38,6 +38,77 @@ + + 64-bit ARM + + + n. A 64-bit version of the ARM architecture. + This term can refer to both AArch66/`aarch64` and to ARM64/`arm64`. + + + Use this format in general cases to refer to names of the architecture for various cloud providers. + + + 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: + + + + + Amazon Web Services (AWS) on 64-bit ARM systems + + + + + Machine types for Microsoft Azure on 64-bit ARM infrastructures + + + + + Refer also to , , , , , and . + + + + + + + 64-bit x86 + + + n. A 64-bit version of the x86 architecture. + This term is a synonym of x86_64. + Use this format in general cases to refer to names of the architecture for various cloud providers. + + + 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: + + + + + Amazon Web Services (AWS) on 64-bit x86 systems + + + + + Machine types for Microsoft Azure on 64-bit x86 infrastructures + + + + + Refer also to , , , , , and . + + + + + + diff --git a/en-US/A.xml b/en-US/A.xml index bf3be12..72791ed 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -69,7 +69,7 @@ v. "Alternate" as a verb means to change between two states or options. - See also . + Refer also to . @@ -84,7 +84,7 @@ "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something", use "an alternative method is to ...". - See also . + Refer also to . @@ -97,38 +97,140 @@ For times of day, use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". - See also . + Refer also to . + + + + + + + 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, amd64 - Correct. Do not use "Hammer", "x86_64", "x86-64", "x64", "64-bit x86" or other variations as the name of this architecture. + n. The AMD 64-bit version of the x86 architecture. + Use this term for Red Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), or command-line interface (CLI) objects. - The correct term for AMD's implementation of this architecture is "AMD64". - When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. + Use the uppercase format (AMD64) in general sentences when referring to Red Hat OpenShift Container Platform features. + Use the lowercase format (amd64) 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: + + + + This operator is supported on AMD64 and ARM64 platforms. + + + + + In this scenario, amd64 is a valid value for X. + + + + - See also . + Refer also to , , , , , and . - + + + + + + + ARM64, arm64 + + + n. A 64-bit version of the ARM architecture. + Use this term for Red Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), and command-line interface (CLI) objects. + + + Use the uppercase format (ARM64) in general sentences when referring to Red Hat OpenShift Container Platform features. + Use lowercase format (arm64) 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: + + + + + In this exercise, you create an ARM64 compute machine set. + + + + + In this scenario, arm64 is a valid value for X. + + + + + Refer also to , , , , , and . + + and/or diff --git a/en-US/B.xml b/en-US/B.xml index ed2bc30..b72d4c5 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -19,7 +19,7 @@ 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 + Refer also to @@ -73,7 +73,7 @@ backwards compatible - Do not use. Instead, use "compatible with earlier versions" to refer to something that is compatible with older equipment or previous versions of software. See also . + Do not use. Instead, use "compatible with earlier versions" to refer to something that is compatible with older equipment or previous versions of software. Refer also to . @@ -106,7 +106,7 @@ basically - Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." See also . + Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." Refer also to . @@ -152,7 +152,7 @@ big data - n., adj. Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. See also . Big data is also never hyphenated, per AP style, even when used as a complex adjective. + n., adj. Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. Refer also to . Big data is also never hyphenated, per AP style, even when used as a complex adjective. @@ -227,9 +227,18 @@ Correct. Named after George Boole, who first developed the concept. - According to the IBM Style Guide, it is acceptable to use "boolean" in API programming information when it refers to a primitive return type. + According to the IBM Style Guide, it is acceptable to use "boolean" (lowercase) in API programming information when it refers to a primitive return type. - + + To set Boolean values in YAML files, use true or false, written lowercase, rather than yes or no, because YAML 1.2 and later versions do not support the latter syntax. + + + For example, the following scenario specifies that a task is run only one time: + +- name: Pause 30 seconds + ansible.builtin.pause: + seconds: 30 + run_once: true @@ -296,7 +305,7 @@ Bps, bps - The abbreviation of bytes per second is Bps. The abbreviation of bits per second is bps. To avoid confusion, do not use at the beginning of a sentence. See also . + The abbreviation of bytes per second is Bps. The abbreviation of bits per second is bps. To avoid confusion, do not use at the beginning of a sentence. Refer also to . @@ -306,7 +315,7 @@ breadcrumb trail - See the IBM Style Guide for initial guidance on how to use this term. + Refer to the IBM Style Guide for initial guidance on how to use this term. @@ -379,10 +388,10 @@ A copy-on-write file system for Linux. Use an uppercase "B" when referring to the file system. When referring to tools, commands, and other utilities that relate to the file system, be faithful to those utilities. - See for more information on this file system. + Refer to for more information on this file system. - See for a list of file-system names and how to present them. + Refer to for a list of file-system names and how to present them. @@ -428,7 +437,7 @@ Ordinarily you would not include the text "button" in a procedure or description. For example, "Click OK to continue" is perfectly acceptable. It might be necessary to distinguish between buttons and links; for example, "Click the Download link". - See also . + Refer also to . diff --git a/en-US/Book_Design.xml b/en-US/Book_Design.xml index ca49a26..6849ac1 100644 --- a/en-US/Book_Design.xml +++ b/en-US/Book_Design.xml @@ -4,7 +4,7 @@ %BOOK_ENTITIES; ]>
- Overall Book Design + Overall Publication Design This section describes a general approach to the overall layout and design of technical documentation. This design was developed specifically for technical documentation and might not suit content produced by other groups. @@ -34,6 +34,12 @@ Introductions + + + + Placement of headings + + @@ -48,10 +54,10 @@
Titles and Subtitles - The title should be a combination of the complete product name, its version, and the name of the book. For example, "Red Hat Satellite 5.6 Installation Guide", or "Red Hat Enterprise Linux 6 Deployment Guide". + The title should be a combination of the complete product name, its version, and the name of the publication. For example, "Red Hat Satellite 6.12 Installation Guide", or "Red Hat Enterprise Linux 9 Deployment Guide". - The subtitle should be a single, succinct phrase that describes the intent of the book; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 8 for all architectures". + The subtitle should be a single, succinct phrase that describes the intent of the publication; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 9 for All Architectures".
@@ -71,23 +77,23 @@ - A suitable abstract covers the high-level topics of the book, and is probably a good place to mention the audience. It should cover the following basics: + A suitable abstract covers the high-level topics of the publication, and is probably a good place to mention the audience. It should cover the following basics: - What: What is the purpose of the book or document? A brief summary, for example, "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API." + What: What is the purpose of the publication or document? A brief summary, for example, "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API." - How: How does the book convey its content? That is, is it task-based? Example-driven? A reference guide? For example, "The guide explains each API method and demonstrates examples of data models for input and output." + How: How does the publication convey its content? That is, is it task-based? Example-driven? A reference guide? For example, "The guide explains each API method and demonstrates examples of data models for input and output." - Why (and possibly Who): A basic rationale for why this book exists, and its audience (and elaborate on the target audience inside the book). For example, "This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." + Why (and possibly Who): A basic rationale for why this publication exists, and its audience (and elaborate on the target audience inside the publication). For example, "This publication provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." @@ -101,17 +107,17 @@ "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API. The guide explains each API method and demonstrates examples of data models for input and output. - This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." + This publication provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." - Update or modify each component according to the type of book that you are writing. + Update or modify each component according to the type of publication that you are writing.
Introductions - 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 <product_name>" 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. + The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory tools, that Red Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to <product_name>" near the beginning of the publication to introduce the reader to the product. Do not use "Introduction" to introduce the publication; 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.
diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index e49ea58..f499499 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -8,7 +8,7 @@ Red Hat Technical Writing Style Guide - 6.1 + 6.2 1 diff --git a/en-US/C.xml b/en-US/C.xml index a627a7b..7503cd0 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -46,7 +46,7 @@ When referring to a compact disk, use "CD". For example, "Insert the CD into the CD drive". The plural is "CDs". - See the Word Usage chapter of the IBM Style Guide for more information. + Refer to the Word Usage chapter of the IBM Style Guide for more information. @@ -67,7 +67,7 @@ Correct. Ceph is a distributed storage platform that provides object, block, and file storage. - See + Refer to Do not use alternative capitalization. @@ -129,7 +129,7 @@ Define on first use; generally continuous integration/continuous delivery. It does not mean continuous development, a term with questionable usefulness and only marginal adoption. - See also , , . + Refer also to , , . @@ -153,7 +153,7 @@ - See the Word Usage chapter of the IBM Style Guide for more information. + Refer to the Word Usage chapter of the IBM Style Guide for more information. @@ -186,7 +186,7 @@ cloud - Although cloud is important to Red Hat's business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase "c" when referring to cloud or cloud computing in a general sense. Use a capitalized "C" when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. See also "big data". + Although cloud is important to Red Hat's business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase "c" when referring to cloud or cloud computing in a general sense. Use a capitalized "C" when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. Refer also to "big data". @@ -247,7 +247,7 @@ combo-box - Do not use as an abbreviation for "combination box". See the relevant entry in the IBM Style Guide for further usage information. + Do not use as an abbreviation for "combination box". Refer to the relevant entry in the IBM Style Guide for further usage information. @@ -313,7 +313,7 @@ command line, command prompt, command-line - See the appropriate entries in the IBM Style Guide for an explanation of how to use these terms. + Refer to the appropriate entries in the IBM Style Guide for an explanation of how to use these terms. @@ -348,7 +348,7 @@ communication service provider (CSP) - Another way to refer to a telecommunications provider. See also . + Another way to refer to a telecommunications provider. Refer also to . @@ -358,7 +358,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. See also . + 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 . @@ -511,7 +511,7 @@ n. CVE stands for Common Vulnerabilities and Exposures, and should be capitalized as shown. - See for more information. + Refer to for more information. diff --git a/en-US/Cross_references.xml b/en-US/Cross_references.xml index aba9f6b..4eac3d0 100644 --- a/en-US/Cross_references.xml +++ b/en-US/Cross_references.xml @@ -11,7 +11,7 @@ Formatting is not described in this section. - In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed book, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader. + In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed publication, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader.
The Additional Information Test @@ -29,7 +29,7 @@ Does the paragraph or section consist largely of links? - In running text, each paragraph should contain no more than a couple of links. Links should not occur in every paragraph, and they must not occur in titles, subheadings, figure captions, or table captions. Cross-references interrupt the flow of thought, and can actively interfere with the absorption of information. If the reader needs much extra information, rethink the structure of the section, and enrich the quality of the information. Do not let the cross-references overpower the message. A solution is to add a sentence to the end of the section to indicate where to find more information. + In running text, each paragraph should contain no more than a couple of links. Links should not occur in every paragraph, and they must not occur in titles, subheadings, or figure captions. Cross-references interrupt the flow of thought, and can actively interfere with the absorption of information. If the reader needs much extra information, rethink the structure of the section, and enrich the quality of the information. Do not let the cross-references overpower the message. A solution is to add a sentence to the end of the section to indicate where to find more information. diff --git a/en-US/D.xml b/en-US/D.xml index 8e8f0b3..100ef12 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -116,7 +116,7 @@ Needs review - When presenting specific dates and times numerically, see ISO Standard 8601. For dates, this means YYYMDD is the recommended representation. + When presenting specific dates and times numerically, refer to ISO Standard 8601. For dates, this means YYYMDD is the recommended representation. @@ -189,7 +189,7 @@ dialog box - See the Word Usage chapter of the IBM Style Guide for usage information related to this and similar terms. + Refer to the Word Usage chapter of the IBM Style Guide for usage information related to this and similar terms. @@ -231,7 +231,7 @@ disk, disc - Use "compact disc" or "hard disk". See the IBM Style Guide for more information and example use cases. + Use "compact disc" or "hard disk". Refer to the IBM Style Guide for more information and example use cases. @@ -273,7 +273,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, "Refer to the Getting Started Guide for further information." @@ -316,7 +316,7 @@ downstream - Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "down-stream" or "down stream." + Correct. Use the one-word form for both the nominal and adjectival forms. Refer also to . Do not use "down-stream" or "down stream." diff --git a/en-US/Design.xml b/en-US/Design.xml index 6414394..5a4c4ea 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -15,8 +15,9 @@ Capitalization - The standard for all Red Hat technical documentation is title case for all headings and titles. - Table headings and procedure headings fall under this heading; standard title case capitalization rules apply. + The standard for technical documentation is title case for all headings and titles. + + Table titles and procedure titles fall into this category; standard title case capitalization rules apply. @@ -26,13 +27,13 @@ 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 sentence case for figure captions, legends, diagram labels, and table column headers. They are not classified as titles. Marketing and Brand Capitalization Guide - The Red Hat Marketing and Brand groups use sentence case for most titles and headings, with some exceptions, for example, when referencing an externally produced resource's title. + The Red Hat Marketing and Brand groups and some other groups use sentence case for most titles and headings, with some exceptions, for example, when referencing an externally produced resource's title. @@ -61,6 +62,9 @@ In some cases, a verb might not be appropriate because the content is purely informational. Instead of using a vague verb like "Understanding", "Describing", "Introducing", or "Exploring", either use a more specific verb, or use a noun phrase instead of a verb. A noun phrase is descriptive and omits a verb, for example "Installation Overview" or "The OpenShift Web Console." + + Avoid a title that consists of only one word. + @@ -85,6 +89,11 @@ Cluster Updates + + MetalLB + The MetalLB Component + + @@ -95,24 +104,50 @@ In training content, avoid using a verb such as "Discussing" or "Demonstrating" in objectives for students. Such verbs might refer instead to what the instructor or the course content covers, or to a student group activity in class. - See the IBM Style Guide for more information. + Refer to the IBM Style Guide for more information. Gerunds should be avoided elsewhere. - See . + Refer to . File Names, Commands, and Related Terms - When creating chapter and section titles, do not include file, command, or similar names, and do not include markup elements. + When creating chapter and section titles, do not include file, command, or similar names, and generally 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. +
+ + + + + + + Example + Improvement + + + + + + + Custom Domains and cert-manager Operators with ROSA + Custom Domains and Certificate Management Operators with ROSA + + + + + + + +
+
Documenting Fonts @@ -124,7 +159,7 @@
Documenting the User Interface - In all cases, see the IBM Style Guide for initial guidance. + In all cases, refer to the IBM Style Guide for initial guidance. The following sections highlight exceptions or cases that might otherwise cause confusion. @@ -133,7 +168,7 @@ Depending on the context, an option might be to write around an incorrectly spelled interface item rather than naming it specifically.
- User Interface Elements, Punctuation, and Symbols + User Interface Elements and Punctuation When describing UI elements, do not include punctuation that appears on those elements, unless omission of that punctuation might lead to confusion. @@ -146,16 +181,16 @@ In some cases it is preferred practice to include the object type for the sake of clarity. - Consider the following: + Consider the following example: - Preferred Style for Documenting Symbols and Other Special Characters + Preferred Style for Documenting Icons Click the Upload ( @@ -166,7 +201,7 @@ - See the UI elements chapter in the IBM Style Guide for more information. + Refer to the UI elements chapter in the IBM Style Guide for more information.
Navigating Through Multiple UI Options @@ -249,11 +284,11 @@ "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. + Refer to info libc argument syntax for the full discussion. - See info bash and the IBM Style Guide for further guidance. + Refer to info bash and the IBM Style Guide for further guidance. The following examples are intended to highlight correct usage. @@ -296,7 +331,7 @@ Source options [username@]hostname:/repository_filename) - The optional username, indicated by brackets ([]), followed by the hostname and path to the repository. + The optional username, indicated by brackets, [], followed by the hostname and path to the repository. All aspects of this component must be replaced with valid values. @@ -425,12 +460,27 @@ $ vi myFile.txt Use line continuation characters without the associated PS2 prompts. + + + + On Linux and macOS operating systems, use the Linux shell continuation character (\). + + + + + On Windows operating systems, use the backtick character (`). + + + + + For content that is potentially used in multiple operating systems, use the Linux shell continuation character, and include an explanatory sentence before the command. + @@ -438,39 +488,20 @@ $ vi myFile.txt - - -Wrapping Long Commands with Continuation Characters and Without PS2 Prompts +$ aws iam create-policy --policy-name RosaCloudWatch \ + --policy-document file://policy.json --query Policy.Arn --output text +arn:aws:iam::452954386616:policy/RosaCloudWatch + - 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 - +The ARN in the preceding output is different on your system. +
@@ -585,7 +616,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest In the narrative, do not show the use of su or sudo, but always show privileged commands with the correct prompt. - See for information about command prompts. + Refer to for information about command prompts. @@ -637,7 +668,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest You can also use here documents to describe how to create a file with required content. - For more information about here documents, see + For more information about here documents, refer to The syntax of here documents varies by system, shell, language, and so on. The following example creates the my-script file in the current directory, with the example content. @@ -718,7 +749,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest
Using Extended User and Group Names - Sometimes, the recommended list of user and group names is too restrictive for the scope of a book or article. In such cases, the following extended model is acceptable. + Sometimes, the recommended list of user and group names is too restrictive for the scope of a publication or article. In such cases, the following extended model is acceptable. Using Realistic Usernames @@ -728,8 +759,8 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest - For example, you are the system administrator at Global Banking and you are asked to set up permissions to the accounting directory for the following users: Huong Sabo, Jerlene Paluch, Abby Quincy, Fricis Ritcher, and Jaya Lamont. - Huong is a department manager and needs read access to the accounting directory. Jerlene is the lead accountant and needs both read and write access. + For example, you are the system administrator at Global Banking and you are asked to set up permissions to the accounting directory for the following users: Huong Sabo, Jolene Paluch, Abby Quincy, Francis Ritcher, and Jaya Lamont. + Huong is a department manager and needs read access to the accounting directory. Jolene is the lead accountant and needs both read and write access. Choosing a Realistic Name @@ -747,6 +778,13 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest In examples or scenarios, you can use a person's name and then use a gender-specific pronoun to refer to that name. Vary the use of proper names in documentation. Use names that represent various ethnic backgrounds, genders, and locations. + + + + Include a diverse set of names in your examples to reflect the diversity of the real world. + For example, use gender-inclusive and culturally diverse names that suggest various backgrounds in examples to avoid implying that only certain groups have specific skills. + + @@ -754,10 +792,14 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest + - Include a diverse set of names in your examples to reflect the diversity of the real world. - For example, use male, female, and culturally diverse names that suggest various backgrounds in examples to avoid implying that only certain groups have specific skills. + When choosing names, also consider how those names might appear in email addresses, usernames, and similar contexts. + Avoid name combinations or abbreviations that result in unintended meanings, such as slang. + An example that works well might be "John Smith", with an email address of jsmith@example.com. + However, for the name "Brian Strong", a corresponding email address of bstrong@example.com might not work so well (when read out, it sounds like "be strong"). + Consider also any implications for names in different languages. @@ -876,7 +918,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest - Place an object name before the noun that it modifies rather than after the noun. + In most cases, place an object name before the noun that it modifies rather than after the noun. @@ -903,6 +945,41 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest +
+ + 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. + + + + + + + + + + Example + Improvement + + + + + + + Log in as the admin user with the redhat password. + Log in as the admin user with redhat as the password. + + + + Define the backup_tmp variable with the /tmp value in the defaults/main.yml file. + Define the backup_tmp variable with a value of /tmp in the defaults/main.yml file. + + + + + + +
@@ -974,7 +1051,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest Capitalization Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)". - Not all acronyms are capitalized (for example, "spool"); see the IBM Style Guide or another suitable reference if you are unsure. + Not all acronyms are capitalized (for example, "spool"); refer to the IBM Style Guide or another suitable reference if you are unsure. @@ -996,7 +1073,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest Possessives - Do not use possessives with abbreviations. For examples and more information, see . + Do not use possessives with abbreviations. For examples and more information, refer to . @@ -1067,7 +1144,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest --> Do not use possessives to refer to product names. - For examples and more information, see . + For examples and more information, refer to . @@ -1266,7 +1343,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest 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. + Refer to for information on using the terms "best practices" and "recommended practices" in Red Hat documentation. @@ -1296,9 +1373,9 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest <section id="citing-other-works"> <title>Citing Other Works - Referencing Other Books + Referencing Other Publications - When referencing another book, either internal or external to Red Hat, use the following format: + When referencing another publication, either internal or external to Red Hat, use the following format: @@ -1307,8 +1384,8 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest --> - -Book Title by First name Surname; Publisher. + +Publication Title by First name Surname; Publisher. @@ -1341,8 +1418,9 @@ Book Title by First name Surname; Publisher. - If the URL is excessively long or complex, create a link by using the title of the destination as a label, and put the actual URL in a footnote. For example: See the Classification of Species - http://world-database-of-everything.com/en/classifcation_of_species/mammals.html + If the URL is long or complex, then create a link by using the title of the destination as a label, and put the URL in a footnote. + For example: Refer to the Classification of Species + page for more information. diff --git a/en-US/E.xml b/en-US/E.xml index 6620c31..700ca00 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -30,7 +30,7 @@ Use to refer to earlier releases of products. Do not use "older" or related terms. - See also . + Refer also to . @@ -50,7 +50,7 @@ emdash - Used (informally) to indicate a pause or abrupt change in thought; for emphasis; or to set off a series in a phrase. See for more information. + Used (informally) to indicate a pause or abrupt change in thought; for emphasis; or to set off a series in a phrase. Refer to for more information. @@ -67,7 +67,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, refer to "type". diff --git a/en-US/F.xml b/en-US/F.xml index 81324ec..7fa8f28 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -94,7 +94,7 @@ file extensions (general usage) - See File names, file types, and directory names in the IBM Style Guide. + Refer to File names, file types, and directory names in the IBM Style Guide. @@ -104,7 +104,7 @@ file mode, file name, file system, file type - n. Write as shown, two words, unless used as a variable. See the IBM Style Guide for more information. + n. Write as shown, two words, unless used as a variable. Refer to the IBM Style Guide for more information. 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. Refer to https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html. @@ -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". Refer also to . @@ -278,7 +278,7 @@ This term is both jargon and inaccurate. Nothing is ever really frictionless. Instead, talk about actual improvement in speed or time. - See also . + Refer also to . @@ -297,7 +297,7 @@ Do not use "frontend" as a noun or adjective. - See also . + Refer also to . @@ -328,7 +328,7 @@ fuzzy - Correct only when referring to fuzzy searches. See for details and examples. + Correct only when referring to fuzzy searches. Refer to for details and examples. diff --git a/en-US/G.xml b/en-US/G.xml index fb223ab..32e360a 100644 --- a/en-US/G.xml +++ b/en-US/G.xml @@ -146,7 +146,7 @@ GigE - See . + Refer to . @@ -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. Refer also to . diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 79bdd98..e882786 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -152,7 +152,7 @@ A possessive indicates that something or someone belongs to a person or thing. - For guidance on how to form a possessive, see . + For guidance on how to form a possessive, refer to . Do not use possessives with product names. @@ -215,6 +215,25 @@ + + + You can use the possessive form with the "Red Hat" company name to refer only to the company itself, without identifying any products or services. + + + Examples: + + + + + Use the "DEI" term to refer to Red Hat's diversity, equity, and inclusion efforts and teams. + + + + + Red Hat's approach to hybrid cloud security helps customers implement security across their entire infrastructure. + + + Otherwise, you can use possessives for people and inanimate objects. @@ -913,7 +932,7 @@ 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. + 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. @@ -931,7 +950,7 @@ Split contractions and abbreviations into separate paragraphs. --> No hard and fast rules exist for hyphenation. In general, do not hyphenate unless required for clarity, or your other references declare that hyphens are required. The following is general guidance; if you are unsure about whether to hyphenate, ask your peers. - See also the "Hyphens" topic in the IBM Style Guide. + Refer also to the "Hyphens" topic in the IBM Style Guide. diff --git a/en-US/H.xml b/en-US/H.xml index 5f87a4c..4758366 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -154,7 +154,7 @@ host group - n. Two words. Capitalize the "H" at the beginning of a sentence. See RFC 966 for more details. + n. Two words. Capitalize the "H" at the beginning of a sentence. Refer to RFC 966 for more details. @@ -166,7 +166,7 @@ n. Usually one word. Capitalize the "H" at the beginning of a sentence. - See the IBM Style Guide for more information. + Refer to the IBM Style Guide for more information. @@ -217,7 +217,7 @@ hover help - See . + Refer to . @@ -237,7 +237,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 refer to the HTML version of this documentation ...". When referring to a web page extension, use "html", such as "The main page is index.html." @@ -260,7 +260,7 @@ hybrid IT - The preferred term to refer to IT that spans both traditional and modern infrastructure, or private and public environments, or some combination of them. Because hybrid can indicate either infrastructure or environment, or both, be specific about the underlying combination. See also . + The preferred term to refer to IT that spans both traditional and modern infrastructure, or private and public environments, or some combination of them. Because hybrid can indicate either infrastructure or environment, or both, be specific about the underlying combination. Refer also to . diff --git a/en-US/I.xml b/en-US/I.xml index 541daeb..9b603c5 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". Refer also to . @@ -134,24 +134,41 @@ Intel 64 - Correct. + n. The Intel 64-bit version of the x86 architecture. + Use this format when referring to information that is exclusive to Intel processors. + For Red Hat products, use only for Red Hat Enterprise Linux content. + + + 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. + + + Example: + + + + + This feature can run on only Intel 64 processors. + + + + - See also . + Refer also to , , , , , and . - + + For more information about AMD trademarks, refer to the AMD Trademark Information page at . + --> - For more information about Intel® trademarks, see and . + For more information about Intel trademarks, refer to and . @@ -252,7 +269,7 @@ Intranet, intranet - See the "Word usage" appendix of the IBM Style Guide for guidance. + Refer to the "Word usage" appendix of the IBM Style Guide for guidance. diff --git a/en-US/K.xml b/en-US/K.xml index 31efa55..6ab0f29 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -10,7 +10,7 @@ KB, kB - See the IBM Style Guide for the correct abbreviation to use for specific use cases. + Refer to the IBM Style Guide for the correct abbreviation to use for specific use cases. @@ -93,7 +93,7 @@ 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 . + Refer also to . @@ -119,7 +119,7 @@ keytab - n. (Kerberos) Correct. A keytab (short for "key table") stores long-term keys for one or more principals. For details, see . + n. (Kerberos) Correct. A keytab (short for "key table") stores long-term keys for one or more principals. For details, refer to . diff --git a/en-US/L.xml b/en-US/L.xml index b37b011..28eeb77 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -42,7 +42,7 @@ later - Use to refer to later or more recent releases of products. Do not use "newer" or related terms. See also . + Use to refer to later or more recent releases of products. Do not use "newer" or related terms. Refer also to . @@ -77,7 +77,7 @@ A Linux desktop suite. Do not use "Libre", "Libreoffice", or "Libre Office". - See also + Refer also to @@ -226,17 +226,14 @@ - lookup, look-up, look up + lookup, look up - n. Use the one-word form. + n., adj. Use the one-word form, unhyphenated. v. Use the two-word form. - - 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 6370179..384d379 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -33,7 +33,7 @@ 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. + Refer to the section for additional information about recommendations in Red Hat documentation. @@ -213,19 +213,6 @@ - - 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. - - - - - - core competency @@ -253,7 +240,7 @@ "Visit the following web link to dig deeper into [subject] ...". Using "dig deeper" might translate awkwardly. - Consider rewording: "For detailed information regarding [subject], see [link]." + Consider rewording: "For detailed information regarding [subject], refer to [link]." @@ -833,7 +820,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. Refer to http://en.wikipedia.org/wiki/Blind_Men-anElephant for more information. @@ -1275,7 +1262,7 @@ - See also . + Refer also to . @@ -1641,13 +1628,13 @@ Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of ...), and very large values. - Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). + Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to publication sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate groups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). - See The Chicago Manual of Style, 17th Edition for detailed information on numbering formats. + Refer to The Chicago Manual of Style, 17th Edition for detailed information on numbering formats. diff --git a/en-US/M.xml b/en-US/M.xml index e35a362..d16639b 100644 --- a/en-US/M.xml +++ b/en-US/M.xml @@ -194,7 +194,7 @@ microservice - n. Correct. One word, common noun. Do not use "micro-service" or "micro service". Only capitalize at the beginning of a sentence or in a title. See https://en.wikipedia.org/wiki/Microservices for a definition. + n. Correct. One word, common noun. Do not use "micro-service" or "micro service". Only capitalize at the beginning of a sentence or in a title. Refer to https://en.wikipedia.org/wiki/Microservices for a definition. diff --git a/en-US/N.xml b/en-US/N.xml index 4feaff4..d2fb950 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -117,7 +117,7 @@ Generally, use "number sign" to refer to the # character. - Otherwise, 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. + Otherwise, use "hash" to refer to a hashtag in social media, or to refer to Secure Hash Algorithm (refer to ), 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. diff --git a/en-US/New.xml b/en-US/New.xml index 4f665e9..ff16b09 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -5,6 +5,66 @@ ]>
New in This Release + + Release 6.2 + Update in February 2024 to provide added or updated guidance and to address reported issues. + + + + Added guidance about line continuation for multiple operating systems. + Refer to . + + + Various updates to guidance about punctuation, including in lists and in tables. + Refer to . + + + Updated guidance about referring to special characters. + 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. + Refer to . + + + Updated guidance about referring to named objects: usually as an adjective followed by a noun, but with some stated exceptions. + Refer to . + + + Updated guidance about using realistic usernames, and updated some of the username examples. + Refer to . + + + Added some clarifications about writing titles, and about the use of titles and captions with tables and images. + Refer to . + + + Added guidance about referring to Booleans. + Refer to . + + + Use "refer to" instead of "see" for references. + Refer to . + + + Updated terms that relate to 64-bit architecture: 64-bit ARM, 64-bit x86, AArch64, aarch64, AMD64, amd64, ARM64, arm64, Intel 64, x86_64. + Refer to . + + + Updated terms that relate to archive files: tar, tarball, untar, unzip, zip. + Refer to . + + + New or updated usage entries: lookup, refer to, screenshot, see. + Refer to . + + + Various other fixes. + + + + + Release 6.1 Update in August 2023 to provide added or updated guidance and to address reported issues. @@ -13,66 +73,65 @@ Updated audience information for this guide. - See . + Refer to . Updated guidance about writing titles. - See . + Refer to . Updated guidance on continuation prompts. - See . + Refer to . Updated using realistic usernames. - See . + Refer to . Added guidance on omitting part of an output. - See . + Refer to . Added guidance about possessives with product names and abbreviations. - See . + Refer to . Various additions to the Punctuation section. - See . + Refer to . Restructured "Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly". - See . + Refer to . Rewrote "The Repeatability Test" section and renamed it to "Repetition". - See . + Refer to . Changed "Homographic Verbs" subsection title to "Avoid May and Should". - See . + Refer to . Inclusive naming of default branch. - See . + Refer to . Updated IBM Style access information. - See . + Refer to . Adjusted sentence length guideline. - See . + Refer to . Removed some references that were specific to DocBook. Use "team" or "group" instead of "squad". - See . + Refer to . - New or updated usage entries: application velocity, key ring, Metal-as-a-Service, OTP, smart card, systemwide, virtualized. - See . + Improved formatting of spacing after tables and of displaying footnotes in dark mode. Various other fixes. diff --git a/en-US/O.xml b/en-US/O.xml index 1278f07..69ce00e 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -139,7 +139,7 @@ Do not use. - See . + Refer to . @@ -177,7 +177,7 @@ A kernel oops is an error message that is generated because of a bug in the kernel. Do not use "oops" on its own. Also, avoid using "kernel oops" at the beginning of a sentence. - See also "kernel panic". + Refer also to "kernel panic". @@ -207,7 +207,7 @@ Open InfiniBand - "Open InfiniBand" is deprecated and should not be used. See "InfiniBand" for usage rules regarding the current preferred term for this switched fabric network topology. + "Open InfiniBand" is deprecated and should not be used. Refer to "InfiniBand" for usage rules regarding the current preferred term for this switched fabric network topology. @@ -228,7 +228,7 @@ A Linux desktop suite. Do not use "Openoffice", "Open Office", or "ooo". - See also . + Refer also to . @@ -307,7 +307,7 @@ n. Always lowercase. This is a concept, not a technology or product name. Being a common noun, it normally requires an article. - See also . + Refer also to . diff --git a/en-US/P.xml b/en-US/P.xml index 92f8b79..5a0c92b 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -20,7 +20,7 @@ - See also . + Refer also to . @@ -52,7 +52,7 @@ n. Use PHP when referring to the language in general. Use php when referring to the specific command or some other literal use. - See for specific PHP language information. See for more general information. + Refer to for specific PHP language information. Refer to for more general information. @@ -89,7 +89,7 @@ Do not use. - Instead of saying "Please see the Getting Started Guide", use "See the Getting Started Guide." + Instead of saying "Please refer to the Getting Started Guide", use "Refer to the Getting Started Guide." Technical information requires an authoritative tone; terms of politeness convey the wrong tone for technical information and are not regarded the same way in all cultures. @@ -129,7 +129,7 @@ For times of day, use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "2 PM". - See also . + Refer also to . diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index bb65489..d4baa12 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -14,7 +14,7 @@ Current standards allow the use of a colon or semicolon in a range of different circumstances. Some of these are described in the following sections. - To relate clauses: + To Relate Clauses The following sentences show a connection or shared theme between two clauses, or use the second clause to reiterate or amplify the idea in the first clause: @@ -54,7 +54,7 @@ Try to limit your use of colons and semicolons. Separate sentences with a period if possible. - To introduce a series: + To Introduce a Series A colon is generally used before a series. @@ -142,7 +142,7 @@ - To introduce a list, command, code block, or procedure + To Introduce a List, Command, Code Block, or Procedure If a list, command, code block, or procedure immediately follows a single stem or introductory sentence, then end that sentence with a colon. @@ -265,7 +265,7 @@ PLAY [Gather and display facts for managed nodes] **************************** Commas - In compound sentences: + In Compound Sentences Use a comma to join clauses in a compound sentence, unless the clauses are short and have a similar theme. @@ -320,7 +320,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - With conjunctive adverbs: + With Conjunctive Adverbs When using a conjunctive adverb (such as however, therefore, otherwise, namely, for example, and so on) in a sentence, set it off with commas. @@ -342,7 +342,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - In adverbial clauses and phrases: + In Adverbial Clauses and Phrases If a dependent clause is restrictive (omission affects the meaning of the main clause), do not set it off with commas. If it is nonrestrictive (omission does not affect the main clause), set it off with commas: @@ -382,7 +382,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - In adjectival clauses or phrases: + In Adjectival Clauses or Phrases An adjectival clause that can be dropped without changing the meaning of the sentence is set off with commas. @@ -410,7 +410,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - With coordinate adjectives: + With Coordinate Adjectives Separate coordinate adjectives (two or more adjectives modifying the same noun) with commas. @@ -432,7 +432,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - With series and lists: + With Series and Lists Separate elements in a series of three or more with commas, including a comma before the conjunction if one is used. @@ -563,7 +563,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - As you can see in the previous image, the title of the web page is "OpenShift 3 Etherpad". + 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'. @@ -611,7 +611,10 @@ PLAY [Gather and display facts for managed nodes] ****************************s only need an apostrophe (for example, Dickens' novels). - For guidance on whether to use a possessive, see . + For guidance on whether to use a possessive, refer to . + + + Whether an apostrophe uses a straight character (the same as a straight single quotation mark) or a curly character is determined by considerations that include language, translation, and typography. @@ -625,19 +628,141 @@ PLAY [Gather and display facts for managed nodes] **************************** +
+ Punctuation in Lists + + For information about punctuation in lists, refer to . + + +
+ +
+ Punctuation in Tables + + Use the following guidance for punctuation in tables: + + + If all cells in a table column are complete sentences, then end each cell with a period. + + + If all cells in a table column are sentence fragments, then do not use a period to end each cell. + + + If cells in a table column contain a mixture of complete sentences and sentence fragments, then first consider whether it would be appropriate to make them grammatically parallel (either all complete sentences or all sentence fragments). + However, in some cases, such an approach might not work, where tables are complex and include a variety of content, such as lists of strings, variables, IP addresses, descriptions, or states (selected or cleared). + In such cases, treat each cell as an individual entry, and either use or omit a closing period depending on whether that cell is a complete sentence. + + + Example of a complex table with punctuation: + + + + + + + + + Field + Value + + + + + + + + Question + + + Default domain name + + + + + + Description + + + This domain name is used to set the hostname of the node. + + + + + + Answer variable name + + + global_domain_name + + + + + + Answer type + + + text + + + + + + Required + + + (selected) + + + + + + Minimum length + + + 1 + + + + + + Maximum length + + + 251 + + + + + + Default answer + + + lab.example.com + + + + + +
+ +
+
- Referring to Punctuation Marks + 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: + 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. + 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 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. - Do not use the symbol on its own. + Do not use the symbol on its own. Referring to Punctuation Marks @@ -647,9 +772,21 @@ PLAY [Gather and display facts for managed nodes] **************************** The path contains the library qualifier in braces. + + Referring to Special Characters + + + When a regular user starts a shell, the prompt includes an ending dollar character ($). + + + Use the pipe character (|) to send the output of one program to the input of another program. + + + The hyphen after the greater than symbol (>) indicates that a newline character (\n) is not added to the end of the variable. + - For more details, see the IBM Style Guide. + For more details, refer to the IBM Style Guide.
@@ -685,7 +822,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - ' + ' or ’ Apostrophe @@ -740,8 +877,8 @@ PLAY [Gather and display facts for managed nodes] **************************** - " - Double quotation mark + " or “ ” + Double quotation marks @@ -825,8 +962,8 @@ PLAY [Gather and display facts for managed nodes] **************************** - ' - Single quotation mark + ' or ‘ ’ + Single quotation marks diff --git a/en-US/R.xml b/en-US/R.xml index 1d43bc7..7c7adf5 100644 --- a/en-US/R.xml +++ b/en-US/R.xml @@ -118,7 +118,8 @@ refer to - Do not use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source). Use "See". + Use to provide references within a document, and for cross-references to other resources. + @@ -149,7 +150,7 @@ required - See . + Refer to . @@ -159,7 +160,7 @@ return - When referring to the keyboard key on Solaris or Mac, use Return or return, respectively. See for other platforms. + When referring to the keyboard key on Solaris or Mac, use Return or return, respectively. Refer to for other platforms. diff --git a/en-US/S.xml b/en-US/S.xml index 12575ae..2304099 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -21,7 +21,7 @@ The correct abbreviation for "Software-as-a-Service". - See also . + Refer also to . @@ -47,11 +47,11 @@ - - screen capture + + screenshot - n. Do not use "screen shot", "screenshot", or other terms or variations. See the relevant entry in the IBM Style Guide. + n. Use this term, and write as one word. Do not use other terms or variations. @@ -82,7 +82,7 @@ n., vb. Due to potential legal ramifications, do not use without a qualifier. - See for examples. + Refer to for examples. Using Qualifiers with Sensitive Terms @@ -112,13 +112,18 @@
- + see - Use to refer readers to another resource. Avoid using "refer to" in this context. + For references within a document, and for cross-references to other resources, do not use “see”. Use “refer to”. + + + For descriptions of graphics, explanations of command outputs, and other similar cases, it is acceptable to use “see”. + Alternatively, it might be more concise or precise to replace “see” with another verb in these cases. + For example, instead of using "Click a server link to see the result details", you could use "Click a server link for the result details". + Instead of using "As you can see, these expected Audit events have an AVC Audit record", you could use "As shown in the output, these expected Audit events have an AVC Audit record". - @@ -129,7 +134,7 @@ n. Only use the abbreviation "segfault" if absolutely necessary, and never use it as a verb. - See also "What is a segfault?" on the Red Hat Customer Portal for more information. + Refer also to "What is a segfault?" on the Red Hat Customer Portal for more information. @@ -171,7 +176,7 @@ server-side/server side - See . + Refer to . @@ -221,7 +226,7 @@ Thus "SHA224", "SHA256", "SHA384", and "SHA512" are considered correct when referring to these specific hash functions. - See for full details. + Refer to for full details. @@ -306,7 +311,7 @@ Do not use if it is something the user must do. For example, "You should make a backup" is a suggestion, but "You must make a backup" is a requirement. - See also . + Refer also to . @@ -345,7 +350,7 @@ simply - Do not use. See also . + Do not use. Refer also to . @@ -367,7 +372,7 @@ skill set, skills, knowledge - n. Avoid using "skill set" as much as possible; use "skills" or "knowledge" instead. Do not use "skill set" or "skill-set" as an adjective. Do not use "skill-set knowledge"; it is redundant. See the following examples: + n. Avoid using "skill set" as much as possible; use "skills" or "knowledge" instead. Do not use "skill set" or "skill-set" as an adjective. Do not use "skill-set knowledge"; it is redundant. Refer to the following examples: Example Use of Term "Skillset" Versus "Skills" @@ -684,7 +689,7 @@ a programming and technical sense, it also means "Run the source--help is an option. - See also . + Refer also to . @@ -694,7 +699,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". Refer also to . @@ -704,7 +709,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". Refer also to . @@ -756,7 +761,7 @@ a programming and technical sense, it also means "Run the sourceSAP 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. + Refer to http://www.sybase.com/products/databasemanagement/adaptiveserverenterprise for more information. diff --git a/en-US/Style_Conventions_for_Writers_and_Editors.ent b/en-US/Style_Conventions_for_Writers_and_Editors.ent index c062671..6f5d777 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/T.xml b/en-US/T.xml index 14c8b70..dd11d8f 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -6,21 +6,40 @@ T - - taskbar + + tar - n. One word. Do not use "task bar". + n., adj. The tape archive file format. + Only use in reference to the file format, for example "a .tar file". + Refer to the Word Usage chapter of the IBM Style Guide. + + + v. Do not use to refer to the process of creating a .tar file. + Refer to the Word Usage chapter of the IBM Style Guide. - - tar, tarball + + tarball - n. See the Word Usage chapter of the IBM Style Guide. + n. In most cases, do not use "tarball" to refer to a compressed archive in the .tar format. + Use ".tar file". + In some limited cases, "tarball" might be introduced as a commonly used term for a compressed archive in the .tar format. + In such cases, briefly mentioning the term as an alternative name might be acceptable, but do not use "tarball" as the primary term to refer to compressed archives. + + + + + + + taskbar + + + n. One word. Do not use "task bar". @@ -30,11 +49,11 @@ telco - Preferred abbreviation for "telecommunications company". Do not use "telecom". See also . + Preferred abbreviation for "telecommunications company". Do not use "telecom". Refer also to . 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. - See . + Refer to . @@ -44,7 +63,7 @@ telecommunications service provider - Expand fully on first use, after which "telco" is the preferred abbreviation. "Service provider" is also acceptable as an abbreviation, but be careful in content that mentions different industries or types of services. Do not use in URLs. See . + Expand fully on first use, after which "telco" is the preferred abbreviation. "Service provider" is also acceptable as an abbreviation, but be careful in content that mentions different industries or types of services. Do not use in URLs. Refer to . @@ -70,7 +89,7 @@ n. Do not use to describe where to type commands. Use "command line" instead. - See the Word Usage chapter of the IBM Style Guide for more information. + Refer to the Word Usage chapter of the IBM Style Guide for more information. @@ -133,7 +152,7 @@ throughput - n. The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. See the IBM Style Guide for more information about using measurements and abbreviations. + n. The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. Refer to the IBM Style Guide for more information about using measurements and abbreviations. @@ -174,7 +193,7 @@ n. When capitalized, Token-Ring refers to the PC network architecture that IBM developed. The IBM Token-Ring specification is standardized by the IEEE as the IEEE 802.5 standard. - + @@ -204,7 +223,7 @@ totally - Do not use. See "basically". + Do not use. Refer to "basically". diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 9801c5e..c59c81d 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -111,7 +111,7 @@ - The following discussion provides some initial insight into using lists correctly. See the IBM Style Guide for a full discussion. + The following discussion provides some initial insight into using lists correctly. Refer to the IBM Style Guide for a full discussion. Do not insert a list midway through a sentence and then continue the sentence after the list. @@ -323,10 +323,14 @@
-
Punctuation in Lists +
Punctuation in Lists For each item in a list, start with either a complete sentence or a sentence fragment. + + A complete sentence must include a subject and a verb. + It conveys a complete thought, and can stand on its own. + For a list where all items are complete sentences, end each item with a period. @@ -334,12 +338,12 @@ Example: - Which statement is true about deployments and deployment configurations? + Which statement is true about deployments and deployment configurations? - Deployments use replica sets, and deployment configurations use replication controllers. + Deployments use replica sets, and deployment configurations use replication controllers. @@ -354,7 +358,7 @@ - Deployments use replica sets, and deployment configurations use stateful sets. + Deployments use replica sets, and deployment configurations use stateful sets. @@ -365,27 +369,77 @@ Example: - Which resource type does the Operator Lifecycle Manager use to store information about installed operators? + Kubernetes networking provides the following capabilities: + + + + + Highly coupled container-to-container communications + + + + + Pod-to-pod communications + + + + + Pod-to-service communications + + + + + External-to-service communications + + + + + Sometimes, list items might include some form of a verb, but if they do not also include a subject, then they are not capable of standing on their own. + Such items count as sentence fragments, and are not ended with any punctuation. + + + Example: + + + Common uses for jobs include the following tasks: - Operator group + Initializing or migrating a database - Catalog source + Calculating one-off metrics from information within the cluster + + + + + Creating or restoring from a data backup + + + + + Example: + + + Consider the following settings when creating a route: + + + + + An optional path, for path-based routes - Install plan + A target port that the application listens to - Operator + An encryption strategy, depending on whether you need a secure or an insecure route @@ -398,23 +452,23 @@ - Identifier of the object schema version. + Identifier of the object schema version. - Schema identifier. In this example, the object conforms to the pod schema. + Schema identifier. In this example, the object conforms to the pod schema. Name of the container inside a pod. - Container names are important for oc commands when a pod contains multiple containers. + Container names are important for oc commands when a pod contains multiple containers. - For information about punctuation in lead-in sentences that introduce a list, see . + For information about punctuation in lead-in sentences that introduce a list, refer to .
@@ -607,7 +661,7 @@ rhevm-iso-uploader [options] upload [file1] [file2] [file3] - For information about punctuation in lead-in sentences that introduce a code block, see . + For information about punctuation in lead-in sentences that introduce a code block, refer to .
@@ -624,7 +678,7 @@ Entities can be helpful in some cases, but they are more of a hindrance when used for terms that need translation. Translators must compare the string with the built document to determine what the entity stands for. These entities might even be overlooked and not be translated at all. - To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities that are required to build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a book. Required entities vary by brand; only the following entities are required for a standard book: + To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities that are required to build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a publication. Required entities vary by brand; only the following entities are required for a standard publication: @@ -654,7 +708,7 @@ - Do not include entities such as &PRODNAME; or &VERSION; and so on, or things like &BIBLE; to represent "The King James Bible". To learn more about entities, see the relevant chapter in + Do not include entities such as &PRODNAME; or &VERSION; and so on, or things like &BIBLE; to represent "The King James Bible". To learn more about entities, refer to the relevant chapter in
diff --git a/en-US/U.xml b/en-US/U.xml index 5794a9f..b63c408 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -38,7 +38,7 @@ n. Always lowercase. It is a concept, not a technology or product name. Being a common noun, it normally requires an article. - See also . + Refer also to . @@ -88,6 +88,17 @@ + + + untar + + + v. Do not use. + Refer to the Word Usage chapter of the IBM Style Guide. + + + + untrusted @@ -98,6 +109,17 @@ + + + unzip + + + v. Do not use. + Refer to the Word Usage chapter of the IBM Style Guide. + + + + upgrade @@ -143,7 +165,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. Refer also to . Do not use "up-stream" or "up stream". @@ -166,7 +188,7 @@ n. Include the appropriate protocol, such as http, ftp, or https, at the beginning of URLs. That is, use http://www.redhat.com and not www.redhat.com. - See for more information. + Refer to for more information. @@ -209,7 +231,7 @@ n. Usually one word. Capitalize the "U" at the beginning of a sentence. - See the IBM Style Guide for more information. + Refer to the IBM Style Guide for more information. diff --git a/en-US/V.xml b/en-US/V.xml index e6ae9b1..31f895c 100644 --- a/en-US/V.xml +++ b/en-US/V.xml @@ -78,7 +78,7 @@ - + virtual, virtualized @@ -111,7 +111,7 @@ The term "virtualized guest" should be used only when comparing a "fully virtualized guest" with a "paravirtualized guest". - See also "guest operating system". + Refer also to "guest operating system". diff --git a/en-US/WUG_Intro.xml b/en-US/WUG_Intro.xml index 834f63b..48ec227 100644 --- a/en-US/WUG_Intro.xml +++ b/en-US/WUG_Intro.xml @@ -17,7 +17,7 @@ The status of a trademark can vary from country to country. Therefore, do not attach the symbols for trademark or registered trademark (™ and ®) to any third-party trademarks that you mention in your document unless Red Hat legal asks you to do so. We do mark Red Hat trademarks. - See Copyright Notices and Trademark Legends for more information. + Refer to Copyright Notices and Trademark Legends for more information. diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index c7082ee..48dd375 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -16,6 +16,41 @@ + + x86_64 + + + n. A 64-bit version of the x86 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 this format without backticks in general cases when referring to system architecture. + Use this format in backticks when referring to architecture as a value or parameter. + + + 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: + + + + + Specifies the type of architecture for your server, such as x86_64. + + + + + When specifying the architecture, x86_64 is a valid value. + + + + + Refer also to , , , , , and . + + + + + XEmacs @@ -102,7 +137,8 @@ zip - See the Word Usage chapter of the IBM Style Guide. + v. Do not use. + Refer to the Word Usage chapter of the IBM Style Guide. diff --git a/index.html b/index.html index 22cb2b9..59a6859 100644 --- a/index.html +++ b/index.html @@ -41,8 +41,8 @@