diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1ae65cc --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +*~ +.DS_Store +.idea + +# editor swap files +.*.sw? + +# databases +*.db + +# tmp directory +tmp diff --git a/README.md b/README.md index 85a0d78..5c95deb 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ WritingStyleGuide ================= -A guide to writing clear, concise, and consistent technical documentation. +This guide is the official style guide for Red Hat training and certification content, and for all other technical documentation except as stated. +Red Hat product documentation by Customer Content Services (CCS) follows the Red Hat supplementary style guide at https://redhat-documentation.github.io/supplementary-style-guide/ instead of this Red Hat Technical Writing Style Guide. -The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat. +The Red Hat Technical Writing Style Guide includes everyday punctuation and grammar, common mistakes to avoid, strategies for translation and global audiences, and a word usage dictionary. -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. +This guide is a public guide. It is reviewed and maintained by Red Hat. Contributions from the wider community are always welcomed. -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. +Other resources for technical writing are listed in the "Resources" section of the guide. Dependencies: @@ -15,7 +16,7 @@ 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. +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: 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/Audience.xml b/en-US/Audience.xml index 4e63d5f..4663045 100644 --- a/en-US/Audience.xml +++ b/en-US/Audience.xml @@ -7,16 +7,34 @@ Audience This guide is the official style guide for Red Hat training and certification content, and for all other technical documentation except as stated. - Red Hat product documentation by Customer Content Services (CCS) follows the Red Hat supplementary style guide at instead of this Red Hat Technical Writing Style Guide. + Red Hat product documentation + + follows the Red Hat supplementary style guide at instead of this guide. - The Red Hat Technical Writing Style Guide includes everyday punctuation and grammar, common mistakes to avoid, strategies for translation and global audiences, and a word usage dictionary. + The Red Hat Technical Writing Style Guide includes guidance for everyday punctuation and grammar, common mistakes and how to avoid them, strategies for translation and global audiences, content design guidance, and a word usage dictionary. - This guide is a public guide. It is reviewed and maintained by Red Hat. Contributions from the wider community are always welcomed. + This guide is a public and open source guide. + It is reviewed and maintained primarily by Red Hat. + Contributions from the wider community are always welcome. Other resources for technical writing are listed in . + Of these resources, + IBM Style + + + + + + is available for Red Hat employees to access online, but does not have a wider circulation. + Links in this guide to IBM Style are denoted by a padlock icon + + + + + . diff --git a/en-US/B.xml b/en-US/B.xml index b72d4c5..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 @@ -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. Refer also to . 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, even when used as a compound modifier. @@ -227,7 +227,13 @@ Correct. Named after George Boole, who first developed the concept. - 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. + According to IBM Style + + + + + , + 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. @@ -312,10 +318,15 @@ - breadcrumb trail + breadcrumb, breadcrumb trail - Refer to the IBM Style Guide for initial guidance on how to use this term. + For initial guidance on how to use this term, refer to IBM Style + + + + + . diff --git a/en-US/Book_Design.xml b/en-US/Book_Design.xml index 6849ac1..ffb2da7 100644 --- a/en-US/Book_Design.xml +++ b/en-US/Book_Design.xml @@ -64,7 +64,7 @@
Prefaces - The brands that form part of Publican contain a preface as part of the common content. Whether your publication is for external Red Hat customers, JBoss customers, internal customers, or whomever, the brand you choose should provide a suitable preface. Try to use the standard preface to help maintain consistency, reduce overhead and maintenance, and also to reduce translation costs. If you feel that the preface fails to meet your needs, consider whether or not you are using the correct brand, or if the brand itself requires an update. + The brands that form part of Publican () contain a preface as part of the common content. Whether your publication is for external Red Hat customers, JBoss customers, internal customers, or whomever, the brand you choose should provide a suitable preface. Try to use the standard preface to help maintain consistency, reduce overhead and maintenance, and also to reduce translation costs. If you feel that the preface fails to meet your needs, consider whether or not you are using the correct brand, or if the brand itself requires an update.
@@ -136,7 +136,7 @@ Overview - Do not use "overview" as a title. No justification was found for using it as a title; anywhere that it might be considered is already covered by either better or more common titles. + Use "Overview" in a title only sparingly, and do not use "Overview" as a title on its own. No justification was found for using it as a title; anywhere that it might be considered is already covered by either better or more common titles. diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index f499499..148be76 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -8,7 +8,7 @@ Red Hat Technical Writing Style Guide - 6.2 + 7.1 1 diff --git a/en-US/C.xml b/en-US/C.xml index 7503cd0..478d972 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -6,6 +6,23 @@ C + + call, called + + + Use to refer to code, programs, or scripts that invoke functions or methods. + For example, "A liveness probe is called throughout the lifetime of the application." + + + On the other hand, when referring to the designation of files, objects, or entities within documentation, use the term "named" instead of "called". + This choice promotes clarity and precision in technical content. + + + Refer also to . + + + + can, may @@ -46,7 +63,12 @@ When referring to a compact disk, use "CD". For example, "Insert the CD into the CD drive". The plural is "CDs". - Refer to the Word Usage chapter of the IBM Style Guide for more information. + For more information, refer to the Word Usage section of IBM Style + + + + + . @@ -95,23 +117,12 @@ Do not use "characters" to mean "bytes". In English, bytes and characters can be used interchangeably; in other languages, a single character might consist of multiple bytes. - In computer software, any symbol that requires one byte of storage. This includes all the ASCII and extended ASCII characters, including the space character. In character-based software, everything that appears on the screen, including graphics symbols, is considered to be a character. In graphics-based applications, the term character is generally reserved for letters, numbers, and punctuation. - - - - - - - check - - - Avoid. Use "verify", "ensure", or "read", depending on the context. + In computer software, a character is a symbol, such as a letter or number, that represents information. This includes all the ASCII and extended ASCII characters, including the space character. In character-based software, everything that appears on the screen, including graphics symbols, is considered to be a character. In graphics-based applications, the term character is generally reserved for letters, numbers, and punctuation. - chipset @@ -153,7 +164,12 @@ - Refer to the Word Usage chapter of the IBM Style Guide for more information. + For more information, refer to the Word Usage section of IBM Style + + + + + . @@ -232,6 +248,17 @@ + + code base + + + n. Two words. + Do not use "codebase", outside the specific context of codebase.com. + + + + + colocate, colocation @@ -244,10 +271,16 @@ - combo-box + combo box - Do not use as an abbreviation for "combination box". Refer to the relevant entry in the IBM Style Guide for further usage information. + Do not use as an abbreviation for "combination box". + For further usage information, refer to the relevant entry in IBM Style + + + + + . @@ -310,10 +343,22 @@ - command line, command prompt, command-line + command line, command-line, command prompt - Refer to the appropriate entries in the IBM Style Guide for an explanation of how to use these terms. + Use "command line" to refer to the place where commands are entered. + Use "command line" as a noun, and use "command-line" as an adjective. + + + For more details about how to use these terms, refer to the appropriate entries in IBM Style + + + + + . + + + Refer also to and to . @@ -354,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 @@ -383,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) @@ -454,8 +500,8 @@ cookie - n. A message given to a web browser by a web server. - The browser stores the message in a text file named cookie.txt. + n. Data that is given to a web browser by a web server. + The browser stores the message in a text file that might be named cookie.txt. The message is then sent back to the server each time the browser requests a page from the server. diff --git a/en-US/D.xml b/en-US/D.xml index 100ef12..adbd557 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -23,7 +23,9 @@ dash - In technical publications, the IBM Style Guide recommends not to use em dashes or en dashes at all. Use a colon or other suitable punctuation. + Use a dash to show a range, such as for page numbers, letters, pages, or dates. + Otherwise, do not use dashes in technical content. + Instead, use other punctuation marks, such as commas, parentheses, or a colon. @@ -35,13 +37,13 @@ n. Use the two-word form unless referring to a product name or other proper noun where the one-word form is used. - + @@ -62,13 +64,13 @@ n. Use the two-word form. - + @@ -87,15 +89,8 @@ data store, datastore - n. Use the two-word form. + n. Write as two words, except in a VMware context where the one-word form is required. - - Marketing Publications Exception - - In marketing publications, the one-word form is recommended. - - - @@ -189,7 +184,13 @@ dialog box - Refer to the Word Usage chapter of the IBM Style Guide for usage information related to this and similar terms. + n. Use "dialog box" (not "dialog", "dialogue", or "dialogue box"), to refer to an element that is displayed for a user to interact with a graphical user interface. + + + Use this term regardless of whether a dialog box is modal, where the user must respond to a prompt before the main content of the interface is enabled again, or is non-modal, where the user can continue interacting with the main content when the dialog box is open. + + + For example: "In the Subscriptions window, click Register to open the Register System dialog box." @@ -217,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". Refer to the IBM Style Guide for more information and example use cases. + 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 5a4c4ea..7411bd1 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -30,13 +30,13 @@ Use sentence case for figure captions, legends, diagram labels, and table column headers. They are not classified as titles. - + Punctuation @@ -60,7 +60,7 @@ Activities and subtasks that the user should perform can alternatively use an imperative verb for clarity. Imperative verbs are prescriptive, such as "Create" or "Delete". Example: "Assess the Health of an OpenShift Cluster". - 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." + 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 "OpenShift Operators" or "The OpenShift Web Console." Avoid a title that consists of only one word. @@ -102,9 +102,6 @@ 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. - - - Refer to the IBM Style Guide for more information. @@ -159,7 +156,12 @@
Documenting the User Interface - In all cases, refer to the IBM Style Guide for initial guidance. + For initial guidance in all cases, refer to UI Elements in IBM Style + + + + + . The following sections highlight exceptions or cases that might otherwise cause confusion. @@ -201,23 +203,33 @@ - Refer to the UI elements chapter in the IBM Style Guide for more information. + For more information, refer to UI Elements in IBM Style + + + + + .
- Navigating Through Multiple UI Options + Moving Through Multiple UI Options - Use "Navigate to" when moving through multiple UI options because it covers all cases where you might have to click, point to, press, select, or otherwise make a series of selections to start an action. + Use "go to" when moving through multiple UI options because it covers all cases where you might have to click, point to, press, select, or otherwise make a series of selections to start an action. - For example, "From the OpenShift web console, navigate to Monitoring → Alerting." + For example, "From the OpenShift web console, go to Monitoring → Metrics and enter the following metrics as queries."
- Figures, Illustrations, and Screen Captures + Figures, Illustrations, and Screenshots - Refer to the Figures section in the IBM Style Guide for general advice about using figures, illustrations, and screen captures. + For general advice about using figures, illustrations, and screenshots, refer to Figures in IBM Style + + + + + . The following specific conventions apply to using captions and callouts with figures in Red Hat technical documentation, and are generally recommended. @@ -261,7 +273,7 @@ Preferred Approach to Starting Applications from the Desktop - To start gedit, press the Super key to enter the Activities Overview, type gedit, and then press Enter. + To start gedit, press the Super key to enter the Activities Overview, type gedit, and then press Enter. @@ -288,7 +300,12 @@ - Refer to info bash and the IBM Style Guide for further guidance. + For further guidance, refer to info bash, and to Technical Elements in IBM Style + + + + + . The following examples are intended to highlight correct usage. @@ -484,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. @@ -512,16 +530,49 @@ The ARN in the preceding output is different on your system. For the sake of brevity, do not show all output to the user in all cases, but only those parts of any output that are relevant to the context that is described. Where output is not included, place a marker to show that information is purposely excluded. When shortening the output, use a consistent notation. - Red Hat uses the ...output omitted... notation, starting and ending with an ellipsis, and highlighted in italics. + For omitting entire horizontal lines of output, Red Hat uses the ...output omitted... notation, starting and ending with an ellipsis, and highlighted in italics. -Notation for Excluding Part of Output +Notation for Omitting Horizontal Output [student@workstation image]$ podman build --layers=false -t nexus . STEP 1: FROM ubi8/ubi:8.3 Getting image source signatures ...output omitted... STEP 14: COMMIT ...output omitted... localhost/nexus:latest + + + + For omitting vertical columns of output, omitting partial lines of output, or to shorten long strings in output, Red Hat uses the ellipsis notation (...). + + +Notation for Omitting Vertical Output + [user@host ~]$ oc get csv +NAME DISPLAY ... +barbican-operator.v1.0.0 Barbican Operator ... +cinder-operator.v1.0.0 Cinder Operator ... +designate-operator.v1.0.0 Designate Operator ... +glance-operator.v1.0.0 Glance Operator ... +heat-operator.v1.0.0 Heat Operator ... +horizon-operator.v1.0.0 Horizon Operator ... +...output omitted... +
@@ -637,12 +688,13 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest - As much as possible, leave the systemwide default as become: false or become: no and if a single task needs privileges, set become: true or become: yes on that task. + As much as possible, configure the default setting for become to false. + If a single task needs privileges, then set become: true on that task. - If most tasks in a play require escalated privileges, set the entire play to become: true or become: yes and possibly selectively set individual tasks to become: false or become: no. + If most tasks in a play require escalated privileges, then set the entire play to become: true and selectively set individual tasks that do not need escalated privileges to become: false. @@ -765,10 +817,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest Choosing a Realistic Name - Consider the following points when choosing a realistic name: - Examples taken from the IBM Style Guide and the Google Developer Documentation Style Guide. - - + Consider the following points when choosing a realistic name: @@ -801,6 +850,10 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest 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. + + Refer also to the + Google Developer Documentation Style Guide. + @@ -949,6 +1002,7 @@ 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. + In other cases, a noun might be omitted. @@ -975,6 +1029,83 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest 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. + + @@ -1043,7 +1174,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest First Mentions Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ...". - Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML. + Unless required for the audience or the topic, do not spell out well-known initialisms, such as HTML. @@ -1051,7 +1182,13 @@ 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"); refer to the IBM Style Guide or another suitable reference if you are unsure. + Not all acronyms are capitalized (for example, "spool"); refer to + Capitalization in IBM Style + + + + + or to another suitable reference if you are unsure. @@ -1167,8 +1304,15 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest
Using Non-breaking Spaces + + + The following guidance about using non-breaking spaces applies only to the Red Hat company name and to Red Hat products. + Do not use non-breaking spaces with other companies' product names. + + + - Use a non-breaking space in the following situations to avoid a break across lines: + To keep text together on the same line, use a non-breaking space in the following situations: @@ -1223,9 +1367,6 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest Non-breaking spaces are not needed elsewhere in a product name and might cause undesirable line-breaking behavior. In particular, do not use non-breaking spaces between extended components of Red Hat product names. For example, "Red Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between any of the words after "Red Hat". - - Do not use non-breaking spaces with other companies' product names. -
diff --git a/en-US/E.xml b/en-US/E.xml index 700ca00..7948e7a 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -6,31 +6,41 @@ E - - e-book, e-commerce, e-learning, email + + earlier - Refer to the primary reference for the type of copy you are creating, either AP or IBM. + Use to refer to earlier releases of products. Do not use "older" or related terms. + Refer also to . + - - e.g. + + ebook, e-commerce, e-learning, email - Red Hat technical documentation always expands these abbreviations. Write out "for example". + Refer to the primary reference for the type of copy that you are creating. + + + + edge + + + 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". @@ -46,7 +56,7 @@ - + enter @@ -104,6 +114,22 @@ + + + EPUB + + + Write as shown, and without any variations in styling or capitalization, to refer to this publishing format. + Do not use EPUB as a noun to refer to an EPUB file. + For example, instead of writing "in an EPUB", write "in an EPUB file". + + + EPUB is part of the w3.org publishing standards: + https://www.w3.org/publishing/epub3/ + + + + essentially diff --git a/en-US/F.xml b/en-US/F.xml index 7fa8f28..eccdd6d 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -94,7 +94,12 @@ file extensions (general usage) - Refer to File names, file types, and directory names in the IBM Style Guide. + Refer to Files and Directories in IBM Style + + + + + . @@ -104,7 +109,13 @@ file mode, file name, file system, file type - n. Write as shown, two words, unless used as a variable. Refer to the IBM Style Guide for more information. + n. Write as shown, two words, unless used as a variable. + For more information, refer to IBM Style + + + + + . adj. Hyphenate when used as a compound adjective. For example, "file-system attributes". diff --git a/en-US/G.xml b/en-US/G.xml index 32e360a..9cf59ac 100644 --- a/en-US/G.xml +++ b/en-US/G.xml @@ -30,13 +30,14 @@ GB - Abbreviation of gigabyte. Depending on the type of content you are writing, refer either to The AP Style Guide or the IBM Style Guide. + Abbreviation of gigabyte. + - + - IBM style: Use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file". + Use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file". @@ -101,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 @@ -202,6 +217,36 @@ + + go to + + + Use "go to" for directing readers to a location, including when moving through multiple UI options, because it covers all cases where you might have to click, point to, select, or otherwise make a series of selections to initiate an action. + + + Examples: + + + + + From the OpenShift web console, go to Monitoring → Metrics and enter the following metrics as queries. + + + + + Open a browser and go to + + + + + Go to the student user's home directory. + + + + + + + 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. - Refer also to the "Hyphens" topic in the IBM Style Guide. + Refer to Hyphens in IBM Style + + + + + . @@ -972,7 +985,7 @@ Split contractions and abbreviations into separate paragraphs. --> Hyphenate Complex Adjectives - Hyphenate complex adjectives (compound modifiers). This is when two adjectives work together to modify an object. The hyphen is used when the first adjective modifies the second adjective. For example, cloud-based solutions, right-side paralysis, systemwide menu. + Hyphenate complex adjectives (compound modifiers). This is when two adjectives work together to modify an object. The hyphen is used when the first adjective modifies the second adjective. For example, cloud-based solutions, right-side paralysis, system-wide menu. diff --git a/en-US/H.xml b/en-US/H.xml index 4758366..f3562d2 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -52,6 +52,19 @@ + + + hardened + + + adj. Do not use as a general descriptor for Red Hat's software development model or to describe the value of a Red Hat subscription. + Use this term in the context of security, for example, reducing the attack surface by enhancing code and fixing vulnerabilities. + If this term is used in other contexts, then add a qualifier. + Always add a descriptive phrase to explain: for example, "hardened for security" or "hardened for stability". + + + + he/she @@ -166,7 +179,12 @@ n. Usually one word. Capitalize the "H" at the beginning of a sentence. - Refer to the IBM Style Guide for more information. + For more information, refer to IBM Style + + + + + . diff --git a/en-US/I.xml b/en-US/I.xml index 9b603c5..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 lowercase except in headings or at the start of a sentence. - - - - 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 @@ -269,7 +269,12 @@ Intranet, intranet - Refer to the "Word usage" appendix of the IBM Style Guide for guidance. + For guidance, refer to the Word Usage section of IBM Style + + + + + . diff --git a/en-US/K.xml b/en-US/K.xml index 6ab0f29..b3483fb 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -10,7 +10,12 @@ KB, kB - Refer to the IBM Style Guide for the correct abbreviation to use for specific use cases. + For the correct abbreviation to use for specific use cases, refer to Units of Measurement in IBM Style + + + + + . diff --git a/en-US/L.xml b/en-US/L.xml index 28eeb77..165ced1 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -98,7 +98,7 @@ lifecycle - n., adj. One word. + n., adj. Write as one word, except to refer to an approved product name that includes that term written as two words. @@ -198,11 +198,19 @@ - v. Two words. For example, "to log in as root". + v. Two words. For example, "to log in as the root user". + + In general, use "log in" when referring to Linux-based technologies and platforms. + In some cases, a tool or platform might use "sign in" or other terms to describe starting a session by entering a username and password. + In these cases, align to the terminology that is used in the user interface. + + + Refer also to and . + @@ -214,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 384d379..ac8a695 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -527,7 +527,7 @@ low-hanging fruit - Metaphor. Do not use. + Metaphor. Do not use. Instead, describe the outcome or opportunity in more precise terms, such as "readily achievable goals" or "low-risk, high-yield opportunities". @@ -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 + +
@@ -1168,7 +1202,7 @@ Kubernetes is an open source system that makes it easy to manage containerized applications across multiple hosts. - Kubernetes is an open source system to manage containerized applications across multiple hosts. + Kubernetes is an open source system that manages containerized applications across multiple hosts. @@ -1237,11 +1271,6 @@
- - Tab through the dialog box. Set the tab. Move the tab on the ruler. How to show or hide tabs. Select the tab. - Use the tab key to move through the dialog box. Set the tab stop. Move the tab mark on the ruler. How to show or hide tab characters. Select the View tab in the Options dialog box. - - To create another administrator, click File > New. diff --git a/en-US/M.xml b/en-US/M.xml index d16639b..94d7db4 100644 --- a/en-US/M.xml +++ b/en-US/M.xml @@ -219,6 +219,27 @@ + + + mission-critical + + + adj. Write as shown. + + + Use to refer to software or systems that are essential to fulfilling the core purpose of an organization. + When mission-critical systems fail, the impact is often immediate and always severe. + Mission-critical software can include customer-facing software for ensuring safety and regulatory compliance and core back-end systems, such as databases and enterprise resource planning (ERP) systems. + + + To continue to accomplish its core mission, Red Hat considers software to be mission-critical if it is essential to preventing major loss or sustaining health and safety, data or software security, or regulatory compliance. + + + Examples of failures that are not considered as mission-critical include an outage for routine maintenance, or a system that is down but is not directly affecting customers. + + + + Montecito diff --git a/en-US/N.xml b/en-US/N.xml index d2fb950..8276bc8 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -6,15 +6,35 @@ N + + named + + + When referring to the designation of files, objects, or entities within documentation, use the term "named" instead of "called". + This choice promotes clarity and precision in technical content. + The word "named" directly associates the name with the entity and is more specific in technical contexts. + Use "named" to refer to such items as a file, directory, task, user, or group. + For example, "When you need to store configuration settings, create a directory named configurations to keep your workspace organized." + + + On the other hand, "called" can imply a more casual or informal reference and might introduce ambiguity, because it can also mean "invoked" in the context of functions or methods. + + + Refer also to . + + + + navigate to - Use "Navigate to" when moving through multiple UI options, because it covers all cases where you might have to click, point to, select, or otherwise make a series of selections to initiate an action. - For example, "From the OpenShift web console, navigate to Monitoring → Alerting." + Use "go to", in preference to "navigate to", for directing readers to a location, including when moving through multiple UI options, to cover all cases where you might have to click, point to, select, or otherwise make a series of selections to initiate an action. + For example, "Go to the student user's home directory." + It is acceptable to use the noun form, "navigation", for example "navigation through the interface". - Do not use "Go to", or "point to", or other variations. + Refer to . diff --git a/en-US/New.xml b/en-US/New.xml index ff16b09..0e40fb1 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -5,6 +5,154 @@ ]>
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. + + + + + + Updated references to IBM Style to include a link, either to the guide or to a specific topic page where relevant. + Each link is denoted with a padlock icon, to show that access is currently restricted to IBM and Red Hat employees. + + + Removed content that was specific to marketing content. + Removed references to AP Style. + + + Updated the audience information. + Refer to . + + + Updated the resources information. + Refer to . + + + Updated guidance to use the simpler phrase "go to" rather than "navigate to", for directing readers to a location. + Refer to and . + + + Updated guidance on when to use "named" versus "called" to refer to different items. + Refer to and . + + + Added a definition of "mission-critical". + Refer to . + + + Updated guidance for "command line", "command-line", "command prompt", "shell prompt", and "terminal". + Refer to , , and . + + + Other new or updated usage entries: + dash, data store/datastore, dialog box, EPUB, hardened, Infrastructure as Code (IaC), lifecycle, secure, sign in/sign-in. + Refer to . + + + Removed usage entries: check, emdash. + + + Updated guidance on using "Overview" in a title. + Refer to . + + + Clarified the use of non-breaking spaces. + Refer to . + + + Added guidance on notation for omitting vertical output. + Refer to . + + + Updated guidance on when to use compact spacing in lists. + Refer to . + + + Added the pipe character to the table of special characters. + Refer to . + + + If dark mode is selected, it now persists across web page refreshes. + + + Various other fixes. + + + + Release 6.2 Update in February 2024 to provide added or updated guidance and to address reported issues. @@ -20,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. @@ -116,7 +264,12 @@ Refer to . - Updated IBM Style access information. + Updated IBM Style + + + + + access information. Refer to . @@ -249,7 +402,12 @@ - Accessing IBM Style online. + Accessing IBM Style + + + + + online. Updated guidance for long commands. @@ -288,7 +446,12 @@ Release 5.0 - Major update in July 2021 to align with some recent changes in IBM Style: + Major update in July 2021 to align with some recent changes in IBM Style + + + + + : diff --git a/en-US/P.xml b/en-US/P.xml index 5a0c92b..3c89e9e 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -12,13 +12,13 @@ n. The correct abbreviation for "Platform-as-a-Service". In the spelled-out version of this term and its variants (for example, Infrastructure-as-a-Service and Software-as-a-Service), always use hyphens. - + Refer also to . @@ -139,7 +139,7 @@ pop-up - n, adj. Do not use "popup" or "pop up". + n, adj. Use only if you must specify the type of menu, list, or window. Do not use "popup" or "pop up". @@ -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 d4baa12..38068ca 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -546,7 +546,12 @@ PLAY [Gather and display facts for managed nodes] **************************** When indicating the start or end of a direct quotation, use curly quotation marks. In all other contexts, such as when writing code samples, code syntax, hexadecimal numbers, or hypertext links, use straight quotation marks. - Refer to the "Typographical Considerations" section in the "Quotation Marks" topic in the IBM Style Guide. + Refer to Typographical Considerations in IBM Style + + + + + . In technical documentation, place punctuation marks, including periods, commas, question marks, exclamation points, dashes, and semicolons inside the quotation marks if they are part of the quotation or part of a programming element that uses quotation marks; if not, place punctuation marks outside the quotation marks. @@ -554,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." + + + + + +
@@ -747,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: @@ -757,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. @@ -776,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. @@ -786,7 +810,12 @@ PLAY [Gather and display facts for managed nodes] **************************** - For more details, refer to the IBM Style Guide. + For more details, refer to Punctuation and Symbols in IBM Style + + + + + .
@@ -875,6 +904,11 @@ PLAY [Gather and display facts for managed nodes] **************************** , Comma + + + $ + Dollar sign + " or “ ” @@ -913,7 +947,7 @@ PLAY [Gather and display facts for managed nodes] **************************** > - Greater than symbol + Greater-than symbol @@ -923,7 +957,7 @@ PLAY [Gather and display facts for managed nodes] **************************** < - Less than symbol + Less-than symbol @@ -945,6 +979,11 @@ PLAY [Gather and display facts for managed nodes] **************************** . Period; dot (when not referring to punctuation) + + + | + Pipe character + + diff --git a/en-US/Resources.xml b/en-US/Resources.xml index d07160f..b62d223 100644 --- a/en-US/Resources.xml +++ b/en-US/Resources.xml @@ -6,38 +6,56 @@ Resources - This section lists some books and websites for you to consult on your quest to create a better document. + This section lists some helpful resources for creating effective technical content. - The guides that you refer to first are generally dictated by the type of material that you are writing. It is important to establish this point first because the guidelines in the following references sometimes contradict each other. It does not mean that the guidelines are wrong; different audiences require different writing styles, and different references are sometimes required when you change styles. The following documentation types are recognized: + The type of content that you are writing will determine which resources are most relevant. + In general, consult company-specific style guides before general resources. + The guidelines in the following references sometimes contradict each other. + It does not mean that the guidelines are wrong; rather, different audiences and genres require different writing styles, and different references are sometimes required when you change styles. + + + The following technical content types are within the scope of this guide: - Technical content: software manuals and documentation, user guides, training courses + Software manuals and documentation - + - Technical collateral: white papers and technology briefs + Training courses - + - Marketing content: advertising, promotions, articles + User guides + + + White papers + + + + + + + + The following content types are outside the scope of this guide: + - Corporate collateral: related to company or products + Marketing content: advertising, articles, press releases, promotions - Press releases + Corporate content about the company or its products @@ -46,14 +64,27 @@
- References for Technical Content and Collateral + References for Technical Content - IBM Style Guide. IBM Corporation, latest version. - - - Red Hat employees can now access the latest version of the IBM Style Guide online, at https://www.ibm.com/docs/en/ibm-style/. + IBM Style + + + + + . + IBM Corporation, latest version. + + + Red Hat employees can access the latest version of IBM Style online, at https://www.ibm.com/docs/en/ibm-style/. + IBM Style does not have a wider circulation. + Links in this guide to IBM Style are denoted by a padlock icon + + + + + .
-
+ @@ -279,7 +305,7 @@ shebang - n. Refers to the character sequence consisting of the number sign and exclamation mark (#!) at the beginning of a script. Do not use hashbang or pound-bang or other variations. + n. Refers to the character sequence consisting of the number sign and exclamation point (#!) at the beginning of a script. Do not use hashbang or pound-bang or other variations. @@ -299,7 +325,13 @@ shell prompt - Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use "command prompt", "terminal", or "shell". + Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use "command prompt" or "shell". + + + For example, "If you enter your username and password correctly, then you log in and get a shell prompt." + + + Refer also to and to . @@ -326,17 +358,39 @@ - - sign in + sign-in, sign in - v. Write as two words. For example, "two options are available to sign in". + Write hyphenated as an adjective or noun, or as two words as a verb. - - + + + + adj., n. Hyphenated. For example, "the sign-in page". + + + + + + v. Two words. For example, "to sign in by using your IAM user account ID". + + + + + + In general, use "log in" when referring to Linux-based technologies and platforms. + In some cases, a tool or platform might use "sign in" or other terms to describe starting a session by entering a username and password. + In these cases, align to the terminology that is used in the user interface. + + + Refer also to . + + + + sign in to @@ -346,6 +400,37 @@ + + sign-on, sign on + + + Write hyphenated as an adjective or noun, or as two words as a verb. + + + + + adj., n. Hyphenated. For example, "single sign-on". + + + + + + v. Two words. + + + + + + In general, use "log in" when referring to Linux-based technologies and platforms. + In some cases, a tool or platform might use "sign in" or other terms to describe starting a session by entering a username and password. + In these cases, align to the terminology that is used in the user interface. + + + Refer also to . + + + + simply @@ -461,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™ @@ -471,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 @@ -599,7 +684,10 @@ a programming and technical sense, it also means "Run the sourceSSL - Initialism for Secure Sockets Layer, a protocol developed by Netscape for transmitting private documents over the internet. SSL uses a public key to encrypt data that is transferred over the SSL connection. Most web browsers support SSL, and many websites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:. + Initialism for Secure Sockets Layer, a protocol developed by Netscape for transmitting private documents over the internet. SSL uses a public key to encrypt data that is transferred over the SSL connection. Most web browsers support SSL, and many websites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:. SSL later evolved into Transport Layer Security (TLS). + + + Refer also to . 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/T.xml b/en-US/T.xml index dd11d8f..b966f4c 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -12,11 +12,17 @@ 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. + + + Refer to the Word Usage section of IBM Style + + + + + . @@ -86,11 +92,32 @@ terminal - n. Do not use to describe where to type commands. Use "command line" instead. + n. Use "terminal" to refer to a text-based interface where typed instructions are entered, or to refer to a session of this type. - - Refer to the Word Usage chapter of the IBM Style Guide for more information. + + For example, "Open a terminal and log in to your OpenShift cluster", or "The exercise file captures any error messages from your terminal". + + + Use "command line" instead to refer to the place where commands are entered. + + + For example, "Copy the command from the web console and paste it on the command line." + + + Refer also to and to . + + + @@ -152,7 +179,13 @@ 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. Refer to 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. + For more information about using abbreviations for units of measurement, refer to Units of Measurement in IBM Style + + + + + . @@ -187,13 +220,23 @@ + + + TLS + + + Initialism for Transport Layer Security, a security protocol that provides privacy and data integrity for internet communications. By convention, URLs that require a TLS connection start with https: instead of http:. + + + + token-ring 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. - + diff --git a/en-US/Translation.xml b/en-US/Translation.xml index c59c81d..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. @@ -42,7 +44,7 @@ These appear as numbered lists. Use this list type for multiple entries if you need to refer to one of the entries from elsewhere in your document, or where order is important. - For example, if you need to list the order of operations that are required to prepare for an installation, or list a sequence of events that occurs. + For example, use an ordered list for a sequence of steps to complete a task, or for a sequence of events. Titles are optional. @@ -87,12 +89,12 @@ 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. - Navigation or similar instructions (such as "Navigate to Menu -> Submenu"). + Navigation or similar instructions (such as "Go to Menu -> Submenu"). @@ -100,6 +102,11 @@ Multiple paragraphs, or sentences that wrap to two or more lines. + + + Other sections where your deliverables might benefit from more spacing between list items, for example a list of objectives in a training course. + + Use a list with compact spacing in all other cases. @@ -111,7 +118,13 @@ - The following discussion provides some initial insight into using lists correctly. Refer to the IBM Style Guide for a full discussion. + The following explanation provides some initial guidance for using lists correctly. + For a detailed explanation, refer to Lists in IBM Style + + + + + . Do not insert a list midway through a sentence and then continue the sentence after the list. @@ -154,7 +167,7 @@ - Before you start the installation, follow these steps to ensure a smooth installation: + Before you start the installation, follow these prerequisite steps: @@ -625,13 +638,13 @@ - Troubleshooting Glance. - Troubleshooting the Glance image service. + Troubleshoot Glance. + Troubleshoot the Glance image service. - Installing the maven-changelog-plugin. - Installing the maven-changelog-plugin package. + Install the maven-changelog-plugin. + Install the maven-changelog-plugin package. diff --git a/en-US/U.xml b/en-US/U.xml index b63c408..b37e156 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -48,7 +48,7 @@ uninterruptible - adj. Despite not appearing in the American Heritage Dictionary, this term does appear in the Merriam-Webster Unabridged Dictionary, and is considered acceptable in Red Hat documentation, especially in the context of "uninterruptible power supply (UPS)". + adj. This term appears in the Merriam-Webster Dictionary, and is considered acceptable in Red Hat documentation, especially in the context of "uninterruptible power supply (UPS)". @@ -94,7 +94,12 @@ v. Do not use. - Refer to the Word Usage chapter of the IBM Style Guide. + Refer to the Word Usage section of IBM Style + + + + + . @@ -115,7 +120,12 @@ v. Do not use. - Refer to the Word Usage chapter of the IBM Style Guide. + Refer to the Word Usage section of IBM Style + + + + + . @@ -141,7 +151,7 @@ - + upstream @@ -182,10 +192,10 @@ - URL + URL, URI - 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. + n. Include the appropriate scheme, such as http, ftp, or https, at the beginning of URLs or URIs. That is, use http://www.redhat.com and not www.redhat.com. Refer to for more information. @@ -231,7 +241,12 @@ n. Usually one word. Capitalize the "U" at the beginning of a sentence. - Refer to the IBM Style Guide for more information. + For more information, refer to IBM Style + + + + + . diff --git a/en-US/WUG_References.xml b/en-US/WUG_References.xml index 364183d..dc968e5 100644 --- a/en-US/WUG_References.xml +++ b/en-US/WUG_References.xml @@ -6,13 +6,18 @@ References - the IBM Style Guide + IBM Style + + + + + - Chicago Manual of Style, 17th Edition + Chicago Manual of Style, 18th Edition - American Heritage Dictionary + Merriam-Webster Dictionary diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index 48dd375..3b0832e 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -138,7 +138,12 @@ v. Do not use. - Refer to the Word Usage chapter of the IBM Style Guide. + Refer to the Word Usage section of IBM Style + + + + + . diff --git a/en-US/images/padlock.png b/en-US/images/padlock.png new file mode 100644 index 0000000..2b82af2 Binary files /dev/null and b/en-US/images/padlock.png differ diff --git a/index.html b/index.html index 59a6859..241115c 100644 --- a/index.html +++ b/index.html @@ -41,8 +41,8 @@

- - Red Hat Technical Writing Style Guide v6.2 + + Red Hat Technical Writing Style Guide v7.0

@@ -51,15 +51,15 @@


This guide is the official style guide for Red Hat training and certification content, and for all other technical documentation except as stated. - Red Hat product documentation by Customer Content Services (CCS) follows the Red Hat supplementary style guide instead of this Red Hat Technical Writing Style Guide. + Red Hat product documentation follows the Red Hat Supplementary Style Guide instead of this guide.


- The Red Hat Technical Writing Style Guide includes everyday punctuation and grammar, common mistakes to avoid, strategies for translation and global audiences, and a word usage dictionary. + The Red Hat Technical Writing Style Guide includes guidance for everyday punctuation and grammar, common mistakes and how to avoid them, strategies for translation and global audiences, content design guidance, and a word usage dictionary.


- This guide is a public guide. It is reviewed and maintained by Red Hat. Contributions from the wider community are always welcomed. + This guide is a public and open source guide. It is reviewed and maintained primarily by Red Hat. Contributions from the wider community are always welcome.