From a12ef03aedbb846a4592a5e59e9d4fd444f42008 Mon Sep 17 00:00:00 2001 From: julian-cable <79939933+julian-cable@users.noreply.github.com> Date: Wed, 9 Oct 2024 14:04:32 +0100 Subject: [PATCH 1/8] Merge commits from dev to master branch for 7.0 release (#622) * Working on #450. * Run Vale over Design.xml. This is the end of part 1/4 of "Run Vale over the style guide." Too big a job to try to handle in one issue and PR. * Ongoing updates for #456 * Closes #456 Part 2 of running Vale over the style guide. I also addressed a few other issues along the way, such as one sentence per line and removing old comments. Language.xml in particular contains lots of examples of what not to do, so it produces lots of noise in Vale. * s/may/might/ per Julian's review. * Working on #457 Run Vale of the style guide part 3. * Closes #457 Run Vale over the style guide, part 3. * Remove spurious space. * Closes #458 Run Vale over style guide part 4. * Closes #365 Remove DocBook references. * Closes #78 Update entry for "virtualized". Basically copy/paste from corp guide. * Closes #355. Improve a bit of formatting. * feat: Add advice on naming the default branch in an inclusive way. (#493) * feat: Add advice on naming the default branch in an inclusive way. * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Updated section about writing titles (#492) * Updated section about writing titles * Reverted title ID * Further edits * Updated guidance on continuation prompts (#494) * Various fixes for 6.1 release (#495) * Various fixes for 6.1 release * XML fix * Updated IBM Style access info (#496) * Updated term entries (#497) * Added guidance on omitting part of an output (#500) * Added guidance on omitting part of an output * Updated wording * Typo fix * Updated sample names and other small fixes (#502) * Various fixes (#512) * Implementing various feedback suggestions from Rachel (#513) * Implementing various feedback suggestions from Rachel * Addressed review comments * Addressed further review comment * Added more punctuation guidance (#515) * Added more punctuation guidance * Implemented review feedback * Updated audience description (#518) * Updated audience description * Further updated audience wording * Adding information about posessives (#519) * feat: added section about posessives * feat: here's the actual section * fix: made some revisions * Content and formatting updates * Update en-US/Punctuation.xml Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * fix: made some revisions * fix: made another revision * Removed company name and restructured section * added link in section 3.6 * Final XML fix --------- Co-authored-by: Julian Cable Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * Updated view and edit files section * Added release notes for 6.1 and updated version information (#522) * updating homepage (#525) * 6.2 quick fixes (#544) * Some updates concerning punctuation (#545) * Updated guidance for punctuation and special characters * Enhanced guidance about punctuation in lists * Minor formatting * Content and formatting * Applied feedback * Minor fixes * Word usage updates: screenshot, lookup, see/refer to (#546) * Word usage updates: screenshot, lookup, see/refer to * Addresses one comment * Updates to see/refer to entries * Minor fix * Line continuation for multiple operating systems (#548) * Line continuation for multiple operating systems * Minor edit * Add 64-bit architecture guidance (#547) * Add 64-bit architecture guidance * Implementing edits from review * Updated Boolean guidance and a bug fix (#551) * Updated Boolean guidance and a bug fix * Update to Boolean entry * Reworked entries for tar, tarball, untar, unzip, zip (#552) * Clarify capitalization for table titles (#553) * Updates on referring to object names and using realistic usernames (#554) * Updates on referring to object names and using realistic usernames * Apply review comments * Updates for apostrophes and quotation marks (#557) * Updates for apostrophes and quotation marks * Updated list of punctuation marks * Updated guidance about titles (#559) * Updated guidance about titles * Change 'book' to 'publication' * Footnote update (#560) * adding ulink tag to a url * Replace an invalid URL --------- Co-authored-by: Julian Cable * fix(docs): add some build instructions (#562) * fix(docs): add some build instructions * feat: add build shortcut * Added small comment --------- Co-authored-by: julian-cable * Corrected some titles to use title case (#563) * Add release notes and update version info (#564) * Add release notes and update version info * Minor wording fix * Remove 'check' entry (#579) * Add 'sign-in' (#580) * Add 'sign-in' * Update login, sign-in, sign-on * XML validation fixes * Implement suggestions from Ashley D'Andrea (#589) * Implement suggestions from Ashley D'Andrea * Apply feedback from Rachel * Apply feedback from Ashley * Add guidance for 'named' and 'called' (#591) * Add guidance for 'named' and 'called' * Further edit * Update guidance for 'go to' (#592) * Update guidance for 'go to' * Add a clarification * Add gitignore for untracked files (#590) * Update guidance about 'Overview' as a title (#593) * Clarify guidance for 'lifecycle' (#594) * Remove yes/no as values for Ansible 'become' * Edits to address feedback in #600 * Update en-US/Design.xml * Update en-US/Design.xml * fixes two sentences on one line * Update 'dialog box' entry (#603) * Update 'dialog box' entry * Further updates * Various fixes (#604) * Various fixes * Address comments * Apply final feedback * Wording change * Add 'mission-critical' * Add EPUB * Implement comments * Implement comments * Final fix * Final fix * Update references to IBM Style with links, and remove marketing references (#609) * Mock-up of new link format to IBM Style with padlock icon * Remove marketing references and explain padlock icon in front matter * Update references to IBM Style with links * Implement suggestions part 1 * Implement suggestions part 2 * Update IaC (#612) * Updates for dashes, terminal, omitting output (#618) * Updates for dashes, terminal, omitting output * add shell prompt example * Further updates * Update abstract wording (#619) * Update abstract wording * Minor rewording * Add release notes (#620) * Add release notes * Apply feedback * Add 'hardened', update 'secure', update omitted output (#621) * Add 'hardened', update 'secure', update omitted output * Apply feedback --------- Co-authored-by: daobrien Co-authored-by: David O'Brien Co-authored-by: mweetman-redhat Co-authored-by: Christine Belzie <105683440+CBID2@users.noreply.github.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> Co-authored-by: Harpal Singh <52556240+harpasin@users.noreply.github.com> Co-authored-by: Alex Corcoles Co-authored-by: Ashley D'Andrea Co-authored-by: Steven Bonneville Co-authored-by: Rachel Lee --- .gitignore | 12 ++++ README.md | 11 ++-- en-US/Audience.xml | 24 +++++++- en-US/B.xml | 19 ++++-- en-US/Book_Design.xml | 4 +- en-US/Book_Info.xml | 2 +- en-US/C.xml | 74 ++++++++++++++++------- en-US/D.xml | 31 +++++----- en-US/Design.xml | 120 ++++++++++++++++++++++++++++--------- en-US/E.xml | 24 ++++++-- en-US/F.xml | 15 ++++- en-US/G.xml | 39 ++++++++++-- en-US/Grammar.xml | 17 +++++- en-US/H.xml | 20 ++++++- en-US/I.xml | 11 +++- en-US/K.xml | 7 ++- en-US/L.xml | 12 +++- en-US/Language.xml | 9 +-- en-US/M.xml | 21 +++++++ en-US/N.xml | 26 +++++++- en-US/New.xml | 101 ++++++++++++++++++++++++++++++- en-US/P.xml | 6 +- en-US/Punctuation.xml | 19 +++++- en-US/Resources.xml | 82 +++++++++++++++++-------- en-US/Revision_History.xml | 6 +- en-US/S.xml | 106 +++++++++++++++++++++++++++++--- en-US/T.xml | 57 +++++++++++++++--- en-US/Translation.xml | 27 ++++++--- en-US/U.xml | 31 +++++++--- en-US/WUG_References.xml | 11 +++- en-US/XYZ.xml | 7 ++- en-US/images/padlock.png | Bin 0 -> 645 bytes 32 files changed, 772 insertions(+), 179 deletions(-) create mode 100644 .gitignore create mode 100644 en-US/images/padlock.png diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..1ae65cc9 --- /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 85a0d780..5c95deba 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/Audience.xml b/en-US/Audience.xml index 4e63d5fd..4663045e 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 b72d4c54..c09cfd30 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -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 6849ac1e..ffb2da71 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 f499499f..6371a851 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.0 1 diff --git a/en-US/C.xml b/en-US/C.xml index 7503cd0e..4084c54f 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 + + + + + . @@ -244,10 +260,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 +332,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 . @@ -454,8 +488,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 100ef12d..bb8f48e9 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." @@ -231,7 +232,7 @@ disk, disc - Use "compact disc" or "hard disk". Refer to the IBM Style Guide for more information and example use cases. + Use "compact disc" or "hard disk". diff --git a/en-US/Design.xml b/en-US/Design.xml index 5a4c4ea1..d56e3778 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. @@ -512,16 +529,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 +687,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 +816,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 +849,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. + @@ -1043,7 +1095,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 +1103,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 +1225,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 +1288,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 700ca005..bf7cb4fe 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -7,10 +7,10 @@ E - e-book, e-commerce, e-learning, email + ebook, e-commerce, e-learning, email - Refer to the primary reference for the type of copy you are creating, either AP or IBM. + Refer to the primary reference for the type of copy that you are creating. @@ -46,7 +46,7 @@ - + enter @@ -104,6 +104,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 7fa8f285..eccdd6da 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 32e360a8..9faef8ef 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". @@ -202,6 +203,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 4758366e..f3562d23 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 9b603c5a..a9ec8241 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -27,10 +27,10 @@ - infrastructure as code (IaC) + 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. + Based on search volume, the nonhyphenated full term and camel-case acronym are preferred. Use uppercase "I" and "C". @@ -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 6ab0f298..b3483fbb 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 28eeb773..0b14e967 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 . + diff --git a/en-US/Language.xml b/en-US/Language.xml index 384d379b..f27ce625 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". @@ -1168,7 +1168,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 +1237,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 d16639b4..94d7db41 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 d2fb9505..8276bc84 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 ff16b096..8599bada 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -5,6 +5,86 @@ ]>
New in This Release + + Release 7.0 + Major update in October 2024 with migration to a new hosting site, and 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 . + + + Various other fixes. + + + + + + + Release 6.2 Update in February 2024 to provide added or updated guidance and to address reported issues. @@ -116,7 +196,12 @@ Refer to . - Updated IBM Style access information. + Updated IBM Style + + + + + access information. Refer to . @@ -249,7 +334,12 @@ - Accessing IBM Style online. + Accessing IBM Style + + + + + online. Updated guidance for long commands. @@ -288,7 +378,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 5a0c92bf..9d1c4cfd 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". diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index d4baa129..bb62e9d5 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. @@ -786,7 +791,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 + + + + + .
@@ -945,6 +955,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 d07160fd..b62d223f 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 @@ -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/T.xml b/en-US/T.xml index dd11d8fe..b966f4c5 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 c59c81d3..16373735 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -42,7 +42,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. @@ -92,7 +92,7 @@ - Navigation or similar instructions (such as "Navigate to Menu -> Submenu"). + Navigation or similar instructions (such as "Go to Menu -> Submenu"). @@ -100,6 +100,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 +116,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 +165,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 +636,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 b63c4089..b37e156d 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 364183dd..dc968e51 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 48dd375d..3b0832e0 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 0000000000000000000000000000000000000000..2b82af2a7144f1f8d6647d37c023d56e5a5df980 GIT binary patch literal 645 zcmV;00($+4P)ZgXgFbngSdJ^%m!Ep$a#bVG7w zVRUJ4ZXi@?ZDjydb!8whGayrCa3C@;GBhACG&(UkIx;pOP)#60Q&bP@3Bv#Y0p3YO zK~y-6rINjF6G0S4&+L!wO^g#kfr5}gLcvr)N-Bg!i6T+ZP$4?t0eArl9s+tEAuTNd z3L2CMK@dt}3n_8zfQ_@>pP9K72_}=>C_1ACTmlS{U%CwZO$jy#Vsc=x;aLbO$4n{UHw* zn><^-#nRO|Qf+v%_Px}o0LqPJ^=q46Z@~Sf8&typ&r>YloafSPopyi7D9z6XWm@yM z*G5!z-lnS+M1(;+E`WlQ7lnaI0%Ac$pboEWNjwfnY>uSu$=PhQP?8<}K*8t<&_rch zh?z(E{}OasOSfO4I!^(pdE*HLKp})G2EgBa&hW!s$HQom+$G*A&cQJVE6%xekB-;3PKEdDQ>6nwUIn9* zwX!KL&azj6+g f4=Omaaa;WZmUGSXFl%jT00000NkvXXu0mjfQNI(H literal 0 HcmV?d00001 From a9e701317ded2b154755e1e3f43b9dd3dfdd010e Mon Sep 17 00:00:00 2001 From: Harpal Singh <52556240+harpasin@users.noreply.github.com> Date: Fri, 22 Nov 2024 14:59:38 +0530 Subject: [PATCH 2/8] Updating master (#627) * Working on #450. * Run Vale over Design.xml. This is the end of part 1/4 of "Run Vale over the style guide." Too big a job to try to handle in one issue and PR. * Ongoing updates for #456 * Closes #456 Part 2 of running Vale over the style guide. I also addressed a few other issues along the way, such as one sentence per line and removing old comments. Language.xml in particular contains lots of examples of what not to do, so it produces lots of noise in Vale. * s/may/might/ per Julian's review. * Working on #457 Run Vale of the style guide part 3. * Closes #457 Run Vale over the style guide, part 3. * Remove spurious space. * Closes #458 Run Vale over style guide part 4. * Closes #365 Remove DocBook references. * Closes #78 Update entry for "virtualized". Basically copy/paste from corp guide. * Closes #355. Improve a bit of formatting. * feat: Add advice on naming the default branch in an inclusive way. (#493) * feat: Add advice on naming the default branch in an inclusive way. * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Updated section about writing titles (#492) * Updated section about writing titles * Reverted title ID * Further edits * Updated guidance on continuation prompts (#494) * Various fixes for 6.1 release (#495) * Various fixes for 6.1 release * XML fix * Updated IBM Style access info (#496) * Updated term entries (#497) * Added guidance on omitting part of an output (#500) * Added guidance on omitting part of an output * Updated wording * Typo fix * Updated sample names and other small fixes (#502) * Various fixes (#512) * Implementing various feedback suggestions from Rachel (#513) * Implementing various feedback suggestions from Rachel * Addressed review comments * Addressed further review comment * Added more punctuation guidance (#515) * Added more punctuation guidance * Implemented review feedback * Updated audience description (#518) * Updated audience description * Further updated audience wording * Adding information about posessives (#519) * feat: added section about posessives * feat: here's the actual section * fix: made some revisions * Content and formatting updates * Update en-US/Punctuation.xml Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * fix: made some revisions * fix: made another revision * Removed company name and restructured section * added link in section 3.6 * Final XML fix --------- Co-authored-by: Julian Cable Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * Updated view and edit files section * Added release notes for 6.1 and updated version information (#522) * updating homepage (#525) * 6.2 quick fixes (#544) * Some updates concerning punctuation (#545) * Updated guidance for punctuation and special characters * Enhanced guidance about punctuation in lists * Minor formatting * Content and formatting * Applied feedback * Minor fixes * Word usage updates: screenshot, lookup, see/refer to (#546) * Word usage updates: screenshot, lookup, see/refer to * Addresses one comment * Updates to see/refer to entries * Minor fix * Line continuation for multiple operating systems (#548) * Line continuation for multiple operating systems * Minor edit * Add 64-bit architecture guidance (#547) * Add 64-bit architecture guidance * Implementing edits from review * Updated Boolean guidance and a bug fix (#551) * Updated Boolean guidance and a bug fix * Update to Boolean entry * Reworked entries for tar, tarball, untar, unzip, zip (#552) * Clarify capitalization for table titles (#553) * Updates on referring to object names and using realistic usernames (#554) * Updates on referring to object names and using realistic usernames * Apply review comments * Updates for apostrophes and quotation marks (#557) * Updates for apostrophes and quotation marks * Updated list of punctuation marks * Updated guidance about titles (#559) * Updated guidance about titles * Change 'book' to 'publication' * Footnote update (#560) * adding ulink tag to a url * Replace an invalid URL --------- Co-authored-by: Julian Cable * fix(docs): add some build instructions (#562) * fix(docs): add some build instructions * feat: add build shortcut * Added small comment --------- Co-authored-by: julian-cable * Corrected some titles to use title case (#563) * Add release notes and update version info (#564) * Add release notes and update version info * Minor wording fix * Remove 'check' entry (#579) * Add 'sign-in' (#580) * Add 'sign-in' * Update login, sign-in, sign-on * XML validation fixes * Implement suggestions from Ashley D'Andrea (#589) * Implement suggestions from Ashley D'Andrea * Apply feedback from Rachel * Apply feedback from Ashley * Add guidance for 'named' and 'called' (#591) * Add guidance for 'named' and 'called' * Further edit * Update guidance for 'go to' (#592) * Update guidance for 'go to' * Add a clarification * Add gitignore for untracked files (#590) * Update guidance about 'Overview' as a title (#593) * Clarify guidance for 'lifecycle' (#594) * Remove yes/no as values for Ansible 'become' * Edits to address feedback in #600 * Update en-US/Design.xml * Update en-US/Design.xml * fixes two sentences on one line * Update 'dialog box' entry (#603) * Update 'dialog box' entry * Further updates * Various fixes (#604) * Various fixes * Address comments * Apply final feedback * Wording change * Add 'mission-critical' * Add EPUB * Implement comments * Implement comments * Final fix * Final fix * Update references to IBM Style with links, and remove marketing references (#609) * Mock-up of new link format to IBM Style with padlock icon * Remove marketing references and explain padlock icon in front matter * Update references to IBM Style with links * Implement suggestions part 1 * Implement suggestions part 2 * Update IaC (#612) * Updates for dashes, terminal, omitting output (#618) * Updates for dashes, terminal, omitting output * add shell prompt example * Further updates * Update abstract wording (#619) * Update abstract wording * Minor rewording * Add release notes (#620) * Add release notes * Apply feedback * Add 'hardened', update 'secure', update omitted output (#621) * Add 'hardened', update 'secure', update omitted output * Apply feedback * Updated audience section for Homepage (#623) * updating index page * Update index.html Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * updating index page for v7.0 (#624) * updating index page for the latest version * Update index.html Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Add dark mode enhancement to What's New (#626) --------- Co-authored-by: daobrien Co-authored-by: David O'Brien Co-authored-by: mweetman-redhat Co-authored-by: Christine Belzie <105683440+CBID2@users.noreply.github.com> Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> Co-authored-by: Julian Cable Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> Co-authored-by: Alex Corcoles Co-authored-by: Ashley D'Andrea Co-authored-by: Steven Bonneville Co-authored-by: Rachel Lee --- en-US/New.xml | 6 +++++- index.html | 10 +++++----- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/en-US/New.xml b/en-US/New.xml index 8599bada..1e7fa810 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -7,7 +7,8 @@ New in This Release Release 7.0 - Major update in October 2024 with migration to a new hosting site, and extensive added and updated guidance. + Major update in November 2024, with extensive added and updated guidance. + + + + as Code + + + Use camel case for both the full term and the acronym. + Do not hyphenate. + Some "as Code" acronyms might overlap. + To avoid confusion, always spell out the full term on first use. + + + Examples: + + + + + Configuration as Code (CaC) + + + + + + Infrastructure as Code (IaC) + + + + + + Policy as Code (PaC) + + + + + + + + as long as @@ -423,6 +456,19 @@ + + + as well as + + + Not interchangeable with "and". + "As well as" used in a series places more emphasis on the items preceding it, whereas "and" places equal weight on all items in the series. + For example, "We sell kitchen electronics and china, as well as some gourmet foods." + But "We sell kitchen electronics, china, and silverware." + + + + ATM diff --git a/en-US/B.xml b/en-US/B.xml index c09cfd30..db175434 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -24,6 +24,15 @@ + + + backtrace + + + n. "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback", possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. + + + backup, back up @@ -59,15 +68,6 @@ - - - backtrace - - - n. "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback", possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. - - - backwards compatible diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index 6371a851..148be76c 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -8,7 +8,7 @@ Red Hat Technical Writing Style Guide - 7.0 + 7.1 1 diff --git a/en-US/C.xml b/en-US/C.xml index 4084c54f..478d972d 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -248,6 +248,17 @@ + + code base + + + n. Two words. + Do not use "codebase", outside the specific context of codebase.com. + + + + + colocate, colocation @@ -388,16 +399,7 @@ - - Containers-as-a-Service - - - The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. Refer also to . - - - - container-based @@ -417,6 +419,16 @@ + + + Containers-as-a-Service + + + The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. Refer also to . + + + + continuous delivery (CD) diff --git a/en-US/D.xml b/en-US/D.xml index bb8f48e9..adbd5572 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -218,23 +218,23 @@ Describe, rather than label. - - Disk Druid + + disk, disc - Correct. Do not use "Disk druid", "disk druid", or "diskdruid". This is a partitioning tool that is incorporated into Red Hat Enterprise Linux. + Use "compact disc" or "hard disk". + - - disk, disc + + Disk Druid - Use "compact disc" or "hard disk". + Correct. Do not use "Disk druid", "disk druid", or "diskdruid". This is a partitioning tool that is incorporated into Red Hat Enterprise Linux. - diff --git a/en-US/Design.xml b/en-US/Design.xml index d56e3778..7411bd10 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -501,7 +501,8 @@ $ vi myFile.txt --> - You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required. + Do not use manual line indentation for the second and subsequent lines of commands. + For some output formats, no control is possible over where lines would break, and any indentation might appear as extra spaces in inelegant places. @@ -1001,6 +1002,7 @@ telemetry-operator.v1.0.0 Telemetry Operator ... --> However, in some cases, the sentence might be easier to understand if the noun appears first, or if additional language separates the object name from the noun. For example, if the noun refers to a password, a value, or a status, then consider stating the noun first, or including explanatory language between the object name and the noun, or doing both. + In other cases, a noun might be omitted. @@ -1027,6 +1029,83 @@ telemetry-operator.v1.0.0 Telemetry Operator ... --> Define the backup_tmp variable with a value of /tmp in the defaults/main.yml file. + + The is:clear key is set to the false value. + The is:clear key is set to false. + + + + + + + +
+ +
+
+ Naming of Object Classes + + When naming an object, consider the impact of its name when writing about the object. + Avoid duplication, alliteration, or long names. + In cases where including the class in an object name helps to provide clarity, avoid including the object's class in the last part of its name. + This approach avoids repetition when writing about the object where the noun that follows the object name indicates its class. + + + + + + + + + + Example + Improvement + + + + + + + + The user that you use to log in is the remote-user user. + Log in as the user-remote user. + + + + Go to the local-project project. + Go to the proj-local project. + + + + Use the base-layer layer of the container. + Use the base-image layer of the container. + + + + Create the instance in the prod-environment environment. + Create the instance in the prod environment. + + + + + Use the oc process --parameters command to view the parameter of the roster-template template. + Use the oc process --parameters command to view the parameter of the roster template. + + + + Create the namesList variable in the my-file file as part of the managedCluster cluster. + Create the namesList variable in the file-test file as part of the cluster-managed cluster. + + + + Verify that the famous-quotes-pvc PVC (Persistent Volume Claim) is successfully created. + Verify that the famous-quotes PVC (Persistent Volume Claim) is successfully created. + + diff --git a/en-US/E.xml b/en-US/E.xml index bf7cb4fe..7948e7a3 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -6,6 +6,17 @@ E + + earlier + + + Use to refer to earlier releases of products. Do not use "older" or related terms. + Refer also to . + + + + + ebook, e-commerce, e-learning, email @@ -15,22 +26,21 @@ - - e.g. + + edge - Red Hat technical documentation always expands these abbreviations. Write out "for example". + Describes network elements outside the gateway and server-side or cloud-side functions (for example, "an edge device"). + Do not refer to "the edge" without qualifying it; define the first instance (for example, "the edge of the network"). - - - earlier + + e.g. - Use to refer to earlier releases of products. Do not use "older" or related terms. - Refer also to . + Red Hat technical documentation always expands these abbreviations. Write out "for example". diff --git a/en-US/G.xml b/en-US/G.xml index 9faef8ef..9cf59ac8 100644 --- a/en-US/G.xml +++ b/en-US/G.xml @@ -102,6 +102,20 @@ + + + generative AI, gen AI + + + Unless clarity requires it or the concept is being introduced or explained, "generative artificial intelligence" does not have to be spelled out on first use; the abbreviation "gen AI" is understood and suffices. + When spelling it out, do not capitalize the term. + + + Note: Because generative AI is a relatively new technology concept, the term and how it is applied is evolving, so this guidance might change accordingly. + + + + GEO, geo diff --git a/en-US/I.xml b/en-US/I.xml index a9ec8241..881a55b0 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -25,16 +25,6 @@ - - - Infrastructure as Code (IaC) - - - Based on search volume, the nonhyphenated full term and camel-case acronym are preferred. Use uppercase "I" and "C". - - - - IBM Z @@ -96,6 +86,16 @@ + + + Infrastructure as Code (IaC) + + + Based on search volume, the nonhyphenated full term and camel-case acronym are preferred. Use uppercase "I" and "C". + + + + inline diff --git a/en-US/L.xml b/en-US/L.xml index 0b14e967..165ced11 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -222,6 +222,15 @@ + + + log out of + + + v. Write as three words. Use "log out of", not "log out from". For example, "to log out of the system". + + + look at diff --git a/en-US/Language.xml b/en-US/Language.xml index f27ce625..ac8a695b 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -943,9 +943,26 @@ +
+ Use of "Allow" - Avoid stating that a product or feature allows the user to do something. Focus instead on what the user does. + Except when referring specifically to permission, avoid stating that a product or feature allows the user to do something. + + + Valid Uses of "Allow" to Refer to Permission + + + Some open source licenses allow code to be reused in proprietary products. + + + You can configure the sudo command to allow specific users to run any command as some other user. + + + + In cases that do not refer to permission, whenever possible, focus instead on what the user, service, or agent does, or replace "allow" with a different verb, such as "enable". + +
@@ -970,6 +987,21 @@ You can use collections to separate core Ansible code updates from updates to modules and plug-ins. + + The system menu allows you to switch network and VPN connections on or off. + From the system menu, you can switch network and VPN connections on or off. + + + + The workspace selector displays active workspaces and allows you to switch between workspaces. + The workspace selector displays active workspaces and enables you to switch between workspaces. + + + @@ -980,6 +1012,8 @@ Report an issue + +
diff --git a/en-US/New.xml b/en-US/New.xml index 1e7fa810..0e40fb10 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -5,6 +5,73 @@ ]>
New in This Release + + Release 7.1 + Maintenance release in June 2025, with some added and updated guidance. + + + + Added an entry for "artificial intelligence (AI)". + Refer to . + + + Added an entry for "as Code". + Refer to . + + + Added an entry for "code base", to use in preference to "codebase". + Refer to . + + + Added an entry for "edge". + Refer to . + + + Added an entry for "generative AI, gen AI". + Refer to . + + + Added an entry for "log out of", to use in preference to "log out from". + Refer to . + + + Added an entry for "print queue", to use in preference to "printer queue". + Refer to . + + + Changed guidance to not use manual line indentation for the second and subsequent lines of commands. + Refer to . + + + Added guidance on the use of "allow". + Refer to . + + + Added guidance on the naming of object classes. + Refer to . + + + Added the dollar sign to the table of punctuation marks and special characters. + Refer to . + + + Changed to use hyphenation for "greater-than" and "less-than", to refer to these characters. + Refer to . + + + Updated guidance to not require a noun with object names in all cases. + Refer to . + + + Updated guidance about the number of items in a bulleted list to allow fewer items in specific cases. + Refer to . + + + Various other fixes. + + + + Release 7.0 Major update in November 2024, with extensive added and updated guidance. @@ -84,9 +151,6 @@ Various other fixes. - - - @@ -104,7 +168,7 @@ Updated guidance about referring to special characters. - Refer to . + Refer to . You can use the possessive form of the company name (Red Hat's) to refer to the company itself, not to any products or services. diff --git a/en-US/P.xml b/en-US/P.xml index 9d1c4cfd..3c89e9e7 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -208,6 +208,16 @@ + + + print queue + + + n. Use "print queue", not "printer queue", to refer to a list of print jobs that are sent to a printer. + + + + proof of concept diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index bb62e9d5..38068ca0 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -559,26 +559,45 @@ PLAY [Gather and display facts for managed nodes] **************************** Correct Examples of the Use of Punctuation with Quotation Marks - - For bind mounts, add "bind" and set fstype to "none". - - - Login successful. - ...output omitted... - Using project "default". - - - As in the previous image, the title of the web page is "OpenShift 3 Etherpad". - - - In the program segment, ensure that the value is X'FF'. - - - - Julius Caesar said, "I came. I saw. I conquered." - + + + + + For bind mounts, add "bind" and set fstype to "none". + + + + + + +Login successful. +...output omitted... +Using project "default". + + + + + + + The title of the web page is "OpenShift 3 Etherpad". + + + + + + In the program segment, ensure that the value is X'FF'. + + + + + + Julius Caesar said, "I came. I saw. I conquered." + + + + + +
@@ -752,7 +771,7 @@ PLAY [Gather and display facts for managed nodes] **************************** -
+
Referring to Punctuation Marks and Special Characters To refer to a punctuation mark or special character, use its name alone if it is one of the following standard characters: @@ -762,7 +781,7 @@ PLAY [Gather and display facts for managed nodes] **************************** For all other characters, use the character name followed by the symbol in parentheses. - For special character names that include a noun such as "sign", "symbol", or "character", provide the character name, the noun that describes the symbol, and then the symbol in parentheses, for example "the greater than symbol (>)". + For special character names that include a noun such as "sign", "symbol", or "character", provide the character name, the noun that describes the symbol, and then the symbol in parentheses, for example "the greater-than symbol (>)". For special character names that do not include such nouns, provide the character name and the symbol in parentheses, for example "a forward slash (/)". You can end a sentence with the symbol in parentheses. @@ -781,7 +800,7 @@ PLAY [Gather and display facts for managed nodes] ****************************Referring to Special Characters - When a regular user starts a shell, the prompt includes an ending dollar character ($). + When a regular user starts a shell, the prompt includes an ending dollar sign ($). Use the pipe character (|) to send the output of one program to the input of another program. @@ -885,6 +904,11 @@ PLAY [Gather and display facts for managed nodes] **************************** , Comma + + + $ + Dollar sign + " or “ ” @@ -923,7 +947,7 @@ PLAY [Gather and display facts for managed nodes] **************************** > - Greater than symbol + Greater-than symbol @@ -933,7 +957,7 @@ PLAY [Gather and display facts for managed nodes] **************************** < - Less than symbol + Less-than symbol diff --git a/en-US/S.xml b/en-US/S.xml index fc872347..38e3f54b 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -546,6 +546,15 @@ + + source + + + v. In addition to the generic use of this term as a noun and verb, in +a programming and technical sense, it also means "Run the source command against the named file." + + + Source-Navigator™ @@ -556,15 +565,6 @@ - - source - - - v. In addition to the generic use of this term as a noun and verb, in -a programming and technical sense, it also means "Run the source command against the named file." - - - space diff --git a/en-US/Style_Conventions_for_Writers_and_Editors.ent b/en-US/Style_Conventions_for_Writers_and_Editors.ent index 6f5d7775..63207111 100644 --- a/en-US/Style_Conventions_for_Writers_and_Editors.ent +++ b/en-US/Style_Conventions_for_Writers_and_Editors.ent @@ -1,5 +1,5 @@ - + - \ No newline at end of file + \ No newline at end of file diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 16373735..c7c170ef 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -31,7 +31,9 @@ Bulleted lists - Use this list type for three or more entries where order is not important. + Use this list type when the order of items is not important. + In most cases, a bulleted list should have three or more entries. + In limited cases, specific publications might choose instead to allow fewer entries in a list. Titles are optional. @@ -87,7 +89,7 @@ Nested lists. - Nested lists themselves can use the attribute if they fall outside the bounds of these recommendations. + Nested list items themselves can use the attribute if they fall outside the bounds of these recommendations. From 801d3d1c148aab3ea9c05c9667c6ab9e882f6da4 Mon Sep 17 00:00:00 2001 From: Harpal Singh <52556240+harpasin@users.noreply.github.com> Date: Wed, 4 Jun 2025 14:45:33 +0530 Subject: [PATCH 4/8] Updating homepage version to 7.1 (#649) * Working on #450. * Run Vale over Design.xml. This is the end of part 1/4 of "Run Vale over the style guide." Too big a job to try to handle in one issue and PR. * Ongoing updates for #456 * Closes #456 Part 2 of running Vale over the style guide. I also addressed a few other issues along the way, such as one sentence per line and removing old comments. Language.xml in particular contains lots of examples of what not to do, so it produces lots of noise in Vale. * s/may/might/ per Julian's review. * Working on #457 Run Vale of the style guide part 3. * Closes #457 Run Vale over the style guide, part 3. * Remove spurious space. * Closes #458 Run Vale over style guide part 4. * Closes #365 Remove DocBook references. * Closes #78 Update entry for "virtualized". Basically copy/paste from corp guide. * Closes #355. Improve a bit of formatting. * feat: Add advice on naming the default branch in an inclusive way. (#493) * feat: Add advice on naming the default branch in an inclusive way. * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Updated section about writing titles (#492) * Updated section about writing titles * Reverted title ID * Further edits * Updated guidance on continuation prompts (#494) * Various fixes for 6.1 release (#495) * Various fixes for 6.1 release * XML fix * Updated IBM Style access info (#496) * Updated term entries (#497) * Added guidance on omitting part of an output (#500) * Added guidance on omitting part of an output * Updated wording * Typo fix * Updated sample names and other small fixes (#502) * Various fixes (#512) * Implementing various feedback suggestions from Rachel (#513) * Implementing various feedback suggestions from Rachel * Addressed review comments * Addressed further review comment * Added more punctuation guidance (#515) * Added more punctuation guidance * Implemented review feedback * Updated audience description (#518) * Updated audience description * Further updated audience wording * Adding information about posessives (#519) * feat: added section about posessives * feat: here's the actual section * fix: made some revisions * Content and formatting updates * Update en-US/Punctuation.xml Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * fix: made some revisions * fix: made another revision * Removed company name and restructured section * added link in section 3.6 * Final XML fix --------- Co-authored-by: Julian Cable Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * Updated view and edit files section * Added release notes for 6.1 and updated version information (#522) * updating homepage (#525) * 6.2 quick fixes (#544) * Some updates concerning punctuation (#545) * Updated guidance for punctuation and special characters * Enhanced guidance about punctuation in lists * Minor formatting * Content and formatting * Applied feedback * Minor fixes * Word usage updates: screenshot, lookup, see/refer to (#546) * Word usage updates: screenshot, lookup, see/refer to * Addresses one comment * Updates to see/refer to entries * Minor fix * Line continuation for multiple operating systems (#548) * Line continuation for multiple operating systems * Minor edit * Add 64-bit architecture guidance (#547) * Add 64-bit architecture guidance * Implementing edits from review * Updated Boolean guidance and a bug fix (#551) * Updated Boolean guidance and a bug fix * Update to Boolean entry * Reworked entries for tar, tarball, untar, unzip, zip (#552) * Clarify capitalization for table titles (#553) * Updates on referring to object names and using realistic usernames (#554) * Updates on referring to object names and using realistic usernames * Apply review comments * Updates for apostrophes and quotation marks (#557) * Updates for apostrophes and quotation marks * Updated list of punctuation marks * Updated guidance about titles (#559) * Updated guidance about titles * Change 'book' to 'publication' * Footnote update (#560) * adding ulink tag to a url * Replace an invalid URL --------- Co-authored-by: Julian Cable * fix(docs): add some build instructions (#562) * fix(docs): add some build instructions * feat: add build shortcut * Added small comment --------- Co-authored-by: julian-cable * Corrected some titles to use title case (#563) * Add release notes and update version info (#564) * Add release notes and update version info * Minor wording fix * Remove 'check' entry (#579) * Add 'sign-in' (#580) * Add 'sign-in' * Update login, sign-in, sign-on * XML validation fixes * Implement suggestions from Ashley D'Andrea (#589) * Implement suggestions from Ashley D'Andrea * Apply feedback from Rachel * Apply feedback from Ashley * Add guidance for 'named' and 'called' (#591) * Add guidance for 'named' and 'called' * Further edit * Update guidance for 'go to' (#592) * Update guidance for 'go to' * Add a clarification * Add gitignore for untracked files (#590) * Update guidance about 'Overview' as a title (#593) * Clarify guidance for 'lifecycle' (#594) * Remove yes/no as values for Ansible 'become' * Edits to address feedback in #600 * Update en-US/Design.xml * Update en-US/Design.xml * fixes two sentences on one line * Update 'dialog box' entry (#603) * Update 'dialog box' entry * Further updates * Various fixes (#604) * Various fixes * Address comments * Apply final feedback * Wording change * Add 'mission-critical' * Add EPUB * Implement comments * Implement comments * Final fix * Final fix * Update references to IBM Style with links, and remove marketing references (#609) * Mock-up of new link format to IBM Style with padlock icon * Remove marketing references and explain padlock icon in front matter * Update references to IBM Style with links * Implement suggestions part 1 * Implement suggestions part 2 * Update IaC (#612) * Updates for dashes, terminal, omitting output (#618) * Updates for dashes, terminal, omitting output * add shell prompt example * Further updates * Update abstract wording (#619) * Update abstract wording * Minor rewording * Add release notes (#620) * Add release notes * Apply feedback * Add 'hardened', update 'secure', update omitted output (#621) * Add 'hardened', update 'secure', update omitted output * Apply feedback * Updated audience section for Homepage (#623) * updating index page * Update index.html Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * updating index page for v7.0 (#624) * updating index page for the latest version * Update index.html Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Add dark mode enhancement to What's New (#626) * Some maintenance updates for 7.1 (#635) * Some maintenance updates for 7.1 * Apply feedback and add release notes * A further round of maintenance updates for the 7.1 release (#641) * A further round of maintenance updates for the 7.1 release * Add dollar sign * Minor fix * Further fix * Jcable/allow object class (#643) * Update guidance for 'allow' * Add guidance for naming object classes * Implement feedback * Minor restructure and update release notes * Minor typing fix (#644) * Minor fixes for 'referring to' section * updating hompage version --------- Co-authored-by: daobrien Co-authored-by: David O'Brien Co-authored-by: mweetman-redhat Co-authored-by: Christine Belzie <105683440+CBID2@users.noreply.github.com> Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> Co-authored-by: Julian Cable Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> Co-authored-by: Alex Corcoles Co-authored-by: Ashley D'Andrea Co-authored-by: Steven Bonneville Co-authored-by: Rachel Lee --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 241115c8..eb872bec 100644 --- a/index.html +++ b/index.html @@ -42,7 +42,7 @@

- Red Hat Technical Writing Style Guide v7.0 + Red Hat Technical Writing Style Guide v7.1

From 795c2d8134cf22c4726833767f2ab0742cd20aa7 Mon Sep 17 00:00:00 2001 From: Harpal Singh Date: Wed, 18 Mar 2026 10:23:55 +0530 Subject: [PATCH 5/8] xml error fix --- .gitignore | 1 + en-US/C.xml | 11 ----------- en-US/P.xml | 10 ---------- 3 files changed, 1 insertion(+), 21 deletions(-) diff --git a/.gitignore b/.gitignore index 1ae65cc9..95593dee 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ # tmp directory tmp +publish \ No newline at end of file diff --git a/en-US/C.xml b/en-US/C.xml index fbdc5d16..a600d729 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -271,17 +271,6 @@ - - - code base - - - n. Two words. - Do not use "codebase", outside the specific context of codebase.com. - - - - diff --git a/en-US/P.xml b/en-US/P.xml index b16a66a4..b5321cea 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -231,16 +231,6 @@ - - - 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 From 0fa14a3ccda048bdb03f418562051fa923f3714a Mon Sep 17 00:00:00 2001 From: Harpal Singh Date: Wed, 18 Mar 2026 10:42:25 +0530 Subject: [PATCH 6/8] removing line --- en-US/Design.xml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 57b9606a..a8e1f5be 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -855,11 +855,7 @@ telemetry-operator.v1.0.0 Telemetry Operator ... --> Refer also to the Google Developer Documentation Style Guide. - - Refer also to the - Google Developer Documentation Style Guide. - - + From 604e5e5e262cec53a5a444971dfa579791e2f3d5 Mon Sep 17 00:00:00 2001 From: Harpal Singh Date: Wed, 18 Mar 2026 10:43:32 +0530 Subject: [PATCH 7/8] minor update --- en-US/Design.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index a8e1f5be..8d939641 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -855,7 +855,7 @@ telemetry-operator.v1.0.0 Telemetry Operator ... --> Refer also to the Google Developer Documentation Style Guide. - + From e7ab2022ee54b6e49950584335a3024830d02302 Mon Sep 17 00:00:00 2001 From: Harpal Singh Date: Wed, 18 Mar 2026 10:44:40 +0530 Subject: [PATCH 8/8] minor update --- en-US/C.xml | 2 +- en-US/Design.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/en-US/C.xml b/en-US/C.xml index a600d729..1e64cf39 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -271,7 +271,7 @@ - + colocate, colocation diff --git a/en-US/Design.xml b/en-US/Design.xml index 8d939641..c2c67a60 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -855,7 +855,7 @@ telemetry-operator.v1.0.0 Telemetry Operator ... --> Refer also to the Google Developer Documentation Style Guide. - +