From 846302d96ffba7b68f0b51fabd56f9e2691230b9 Mon Sep 17 00:00:00 2001 From: julian-cable Date: Wed, 4 Sep 2024 10:02:55 +0100 Subject: [PATCH 1/5] Mock-up of new link format to IBM Style with padlock icon --- en-US/Punctuation.xml | 7 ++++++- en-US/images/padlock.png | Bin 0 -> 645 bytes 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100644 en-US/images/padlock.png diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 841e9cc..8c4e573 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. 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 71b3b85cdff6e4f3970de966d5702b639df56b39 Mon Sep 17 00:00:00 2001 From: julian-cable Date: Wed, 4 Sep 2024 12:01:14 +0100 Subject: [PATCH 2/5] Remove marketing references and explain padlock icon in front matter --- en-US/Audience.xml | 7 +++++++ en-US/B.xml | 2 +- en-US/D.xml | 8 ++++---- en-US/Design.xml | 4 ++-- en-US/P.xml | 4 ++-- en-US/Resources.xml | 28 ++++++++++++++++++++++------ en-US/U.xml | 4 ++-- en-US/WUG_References.xml | 4 ++-- 8 files changed, 42 insertions(+), 19 deletions(-) diff --git a/en-US/Audience.xml b/en-US/Audience.xml index 4e63d5f..0f39a05 100644 --- a/en-US/Audience.xml +++ b/en-US/Audience.xml @@ -17,6 +17,13 @@ Other resources for technical writing are listed in . + Of these resources, IBM Style is now available for Red Hat employees to access online, but does not have a wider circulation. + Links in this guide to IBM Style are denoted by a padlock icon + + + + + . diff --git a/en-US/B.xml b/en-US/B.xml index b72d4c5..e35520b 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 complex adjective. diff --git a/en-US/D.xml b/en-US/D.xml index 206a541..38113ed 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -35,13 +35,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 +62,13 @@ n. Use the two-word form. - + diff --git a/en-US/Design.xml b/en-US/Design.xml index 4f28c84..491096b 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 diff --git a/en-US/P.xml b/en-US/P.xml index 82379cd..9d1c4cf 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 . diff --git a/en-US/Resources.xml b/en-US/Resources.xml index d07160f..16288b2 100644 --- a/en-US/Resources.xml +++ b/en-US/Resources.xml @@ -9,7 +9,10 @@ This section lists some books and websites for you to consult on your quest to create a better document. - 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 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 within the scope of this guide: @@ -23,6 +26,12 @@ + + + + + The following documentation types are outside the scope of this guide: + Marketing content: advertising, promotions, articles @@ -50,10 +59,17 @@ - IBM Style Guide. IBM Corporation, latest version. + IBM Style. 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/. + Red Hat employees can now 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 + + + + + . upstream diff --git a/en-US/WUG_References.xml b/en-US/WUG_References.xml index 364183d..a3a5877 100644 --- a/en-US/WUG_References.xml +++ b/en-US/WUG_References.xml @@ -6,10 +6,10 @@ References - the IBM Style Guide + the IBM Style - Chicago Manual of Style, 17th Edition + Chicago Manual of Style, 18th Edition American Heritage Dictionary From 3950ab88db013ae8837b2e1217d499d7b7925104 Mon Sep 17 00:00:00 2001 From: julian-cable Date: Wed, 4 Sep 2024 15:04:06 +0100 Subject: [PATCH 3/5] Update references to IBM Style with links --- README.md | 4 ++-- en-US/B.xml | 6 +++--- en-US/C.xml | 10 +++++----- en-US/D.xml | 11 ++++++++-- en-US/Design.xml | 41 +++++++++++++++++++++++++++++--------- en-US/F.xml | 9 +++++++-- en-US/G.xml | 2 +- en-US/Grammar.xml | 7 ++++++- en-US/H.xml | 2 +- en-US/I.xml | 2 +- en-US/K.xml | 7 ++++++- en-US/Punctuation.xml | 7 ++++++- en-US/Revision_History.xml | 6 +++--- en-US/T.xml | 17 +++++++++++----- en-US/Translation.xml | 8 +++++++- en-US/U.xml | 6 +++--- en-US/XYZ.xml | 2 +- 17 files changed, 105 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 85a0d78..43b7d14 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ The Red Hat Style Guide and Word Usage Dictionary is a joint effort by vari It covers recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases. -It is based on The IBM Style Guide but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions. +It is based on IBM Style but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions. Dependencies: @@ -15,7 +15,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/B.xml b/en-US/B.xml index e35520b..f0d1fd6 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -227,7 +227,7 @@ 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 +312,10 @@ - breadcrumb trail + breadcrumb, breadcrumb trail - Refer to the IBM Style Guide for initial guidance on how to use this term. + Refer to IBM Style for initial guidance on how to use this term. diff --git a/en-US/C.xml b/en-US/C.xml index d771def..5882720 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -63,7 +63,7 @@ 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. + Refer to the Word Usage chapter of IBM Style for more information. @@ -159,7 +159,7 @@ - Refer to the Word Usage chapter of the IBM Style Guide for more information. + Refer to the Word Usage chapter of IBM Style for more information. @@ -250,10 +250,10 @@ - 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". Refer to the relevant entry in IBM Style for further usage information. @@ -319,7 +319,7 @@ command line, command prompt, command-line - Refer to the appropriate entries in the IBM Style Guide for an explanation of how to use these terms. + Refer to the appropriate entries in IBM Style for an explanation of how to use these terms. diff --git a/en-US/D.xml b/en-US/D.xml index 38113ed..8e35148 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -23,7 +23,14 @@ 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. + In technical publications, IBM Style recommends not to use em dashes. Use a colon or other suitable punctuation. + En dashes are used to show a range. + Refer to Dashes in IBM Style + + + + + . @@ -230,7 +237,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 491096b..7f9af52 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -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,7 +203,12 @@ - Refer to the UI elements chapter in the IBM Style Guide for more information. + For more information, refer to UI Elements in IBM Style + + + + + .
Moving Through Multiple UI Options @@ -217,7 +224,12 @@
Figures, Illustrations, and Screenshots - Refer to the Figures section in the IBM Style Guide for general advice about using figures, illustrations, and screenshots. + 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. @@ -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. @@ -767,7 +784,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. + Examples taken from IBM Style and the Google Developer Documentation Style Guide. @@ -1052,7 +1069,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. diff --git a/en-US/F.xml b/en-US/F.xml index 7fa8f28..c3df6e2 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,7 @@ 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. Refer to IBM Style for more information. 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 ab39c40..9faef8e 100644 --- a/en-US/G.xml +++ b/en-US/G.xml @@ -31,7 +31,7 @@ Abbreviation of gigabyte. - + 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 + + + + + . diff --git a/en-US/H.xml b/en-US/H.xml index 4758366..8f9e667 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -166,7 +166,7 @@ n. Usually one word. Capitalize the "H" at the beginning of a sentence. - Refer to the IBM Style Guide for more information. + Refer to IBM Style for more information. diff --git a/en-US/I.xml b/en-US/I.xml index 9b603c5..74f8e3e 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -269,7 +269,7 @@ Intranet, intranet - Refer to the "Word usage" appendix of the IBM Style Guide for guidance. + Refer to the Word usage chapter of IBM Style for guidance. diff --git a/en-US/K.xml b/en-US/K.xml index 6ab0f29..b3483fb 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -10,7 +10,12 @@ KB, kB - Refer to the IBM Style Guide for the correct abbreviation to use for specific use cases. + For the correct abbreviation to use for specific use cases, refer to Units of Measurement in IBM Style + + + + + . diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 8c4e573..bb62e9d 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -791,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 + + + + + .
diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml index 3bab0ad..e1fe825 100644 --- a/en-US/Revision_History.xml +++ b/en-US/Revision_History.xml @@ -310,7 +310,7 @@ BZ 921826 Add entry for "best practices" to chapter "Avoiding Slang". BZ 916000 Add entry for correct use of product version numbers to Design chapter. Fix entry for VDSM; not an acronym. - BZ 909015 Entry for "refer to" conflicts with IBM style guide. + BZ 909015 Entry for "refer to" conflicts with IBM Style. Update some punctuation standards and cross references. @@ -416,7 +416,7 @@ Updates to and integration of Chapters X, Y, and Z. Updated section on "Avoiding Slang". Removed some redundant entries. - Various cleanups based on IBM Style Guide. + Various cleanups based on IBM Style. New entries from Word Nerds discussions. @@ -453,7 +453,7 @@ Removed some redundant entries. - Patched some entries based on IBM Style Guide. + Patched some entries based on IBM Style. Cleaned up A, B, C, and part of D in Word Usage Dictionary. diff --git a/en-US/T.xml b/en-US/T.xml index 2f3cc59..99ab77e 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -12,11 +12,12 @@ 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 chapter of IBM Style. @@ -89,7 +90,7 @@ n. Do not use to describe where to type commands. Use "command line" instead. - Refer to the Word Usage chapter of the IBM Style Guide for more information. + Refer to the Word Usage chapter of IBM Style for more information. @@ -152,7 +153,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 measurements and abbreviations, refer to Units of Measurement in IBM Style + + + + + . @@ -203,7 +210,7 @@ n. When capitalized, Token-Ring refers to the PC network architecture that IBM developed. The IBM Token-Ring specification is standardized by the IEEE as the IEEE 802.5 standard. - + diff --git a/en-US/Translation.xml b/en-US/Translation.xml index b12d4ba..17fa7e7 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -116,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 insight into 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. diff --git a/en-US/U.xml b/en-US/U.xml index 915f84d..d7c224e 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -94,7 +94,7 @@ v. Do not use. - Refer to the Word Usage chapter of the IBM Style Guide. + Refer to the Word Usage chapter of IBM Style. @@ -115,7 +115,7 @@ v. Do not use. - Refer to the Word Usage chapter of the IBM Style Guide. + Refer to the Word Usage chapter of IBM Style. @@ -231,7 +231,7 @@ n. Usually one word. Capitalize the "U" at the beginning of a sentence. - Refer to the IBM Style Guide for more information. + Refer to IBM Style for more information. diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index 48dd375..ae53408 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -138,7 +138,7 @@ v. Do not use. - Refer to the Word Usage chapter of the IBM Style Guide. + Refer to the Word Usage chapter of IBM Style. From a56b158a3de2e470b8f1cd1acb93009998d167c3 Mon Sep 17 00:00:00 2001 From: julian-cable Date: Thu, 12 Sep 2024 18:31:16 +0100 Subject: [PATCH 4/5] Implement suggestions part 1 --- README.md | 9 +++--- en-US/Audience.xml | 2 +- en-US/C.xml | 4 +-- en-US/I.xml | 2 +- en-US/Resources.xml | 59 +++++++++++++++++++++++++--------------- en-US/T.xml | 4 +-- en-US/U.xml | 6 ++-- en-US/WUG_References.xml | 2 +- en-US/XYZ.xml | 2 +- 9 files changed, 53 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 43b7d14..5c95deb 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ WritingStyleGuide ================= -A guide to writing clear, concise, and consistent technical documentation. +This guide is the official style guide for Red Hat training and certification content, and for all other technical documentation except as stated. +Red Hat product documentation by Customer Content Services (CCS) follows the Red Hat supplementary style guide at https://redhat-documentation.github.io/supplementary-style-guide/ instead of this Red Hat Technical Writing Style Guide. -The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat. +The Red Hat Technical Writing Style Guide includes everyday punctuation and grammar, common mistakes to avoid, strategies for translation and global audiences, and a word usage dictionary. -It covers recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases. +This guide is a public guide. It is reviewed and maintained by Red Hat. Contributions from the wider community are always welcomed. -It is based on IBM Style 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: diff --git a/en-US/Audience.xml b/en-US/Audience.xml index 0f39a05..9f3a48a 100644 --- a/en-US/Audience.xml +++ b/en-US/Audience.xml @@ -17,7 +17,7 @@ Other resources for technical writing are listed in . - Of these resources, IBM Style is now available for Red Hat employees to access online, but does not have a wider circulation. + 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/C.xml b/en-US/C.xml index 5882720..cefe0b9 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -63,7 +63,7 @@ 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 IBM Style for more information. + Refer to the Word Usage section of IBM Style for more information. @@ -159,7 +159,7 @@ - Refer to the Word Usage chapter of IBM Style for more information. + Refer to the Word Usage section of IBM Style for more information. diff --git a/en-US/I.xml b/en-US/I.xml index 74f8e3e..4917042 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -269,7 +269,7 @@ Intranet, intranet - Refer to the Word usage chapter of IBM Style for guidance. + Refer to the Word Usage section of IBM Style for guidance. diff --git a/en-US/Resources.xml b/en-US/Resources.xml index 16288b2..475ebe9 100644 --- a/en-US/Resources.xml +++ b/en-US/Resources.xml @@ -6,47 +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 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 documentation types are within the scope of this guide: + 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 + + + User guides + - - - - The following documentation types are outside the scope of this guide: - - + + - Marketing content: advertising, promotions, articles + 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 @@ -55,14 +64,20 @@
- References for Technical Content and Collateral + References for Technical Content - IBM Style. IBM Corporation, latest version. + IBM Style + + + + + . + IBM Corporation, latest version. - Red Hat employees can now access the latest version of IBM Style online, at https://www.ibm.com/docs/en/ibm-style/. + 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 @@ -113,14 +128,14 @@ - Merriam-Webster Unabridged Dictionary + Merriam-Webster Dictionary - Visit https://www.merriam-webster.com/ for subscription options. + Visit https://www.merriam-webster.com/ - + diff --git a/en-US/T.xml b/en-US/T.xml index 99ab77e..f873289 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -17,7 +17,7 @@ v. Do not use to refer to the process of creating a .tar file. - Refer to the Word Usage chapter of IBM Style. + Refer to the Word Usage section of IBM Style. @@ -90,7 +90,7 @@ n. Do not use to describe where to type commands. Use "command line" instead. - Refer to the Word Usage chapter of IBM Style for more information. + Refer to the Word Usage section of IBM Style for more information. diff --git a/en-US/U.xml b/en-US/U.xml index d7c224e..0d445b3 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,7 @@ v. Do not use. - Refer to the Word Usage chapter of IBM Style. + Refer to the Word Usage section of IBM Style. @@ -115,7 +115,7 @@ v. Do not use. - Refer to the Word Usage chapter of IBM Style. + Refer to the Word Usage section of IBM Style. diff --git a/en-US/WUG_References.xml b/en-US/WUG_References.xml index a3a5877..3d22b33 100644 --- a/en-US/WUG_References.xml +++ b/en-US/WUG_References.xml @@ -12,7 +12,7 @@ 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 ae53408..33f8e1e 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -138,7 +138,7 @@ v. Do not use. - Refer to the Word Usage chapter of IBM Style. + Refer to the Word Usage section of IBM Style. From 07d73aef835ee690e1dcb220416e785e5b9a10c5 Mon Sep 17 00:00:00 2001 From: julian-cable Date: Fri, 13 Sep 2024 11:56:10 +0100 Subject: [PATCH 5/5] Implement suggestions part 2 --- en-US/Audience.xml | 11 +++++++++-- en-US/B.xml | 17 ++++++++++++++--- en-US/C.xml | 29 +++++++++++++++++++++++++---- en-US/D.xml | 7 ++++++- en-US/Design.xml | 11 ++++++----- en-US/F.xml | 8 +++++++- en-US/H.xml | 7 ++++++- en-US/I.xml | 7 ++++++- en-US/New.xml | 21 ++++++++++++++++++--- en-US/Resources.xml | 19 +++++++++++-------- en-US/T.xml | 16 +++++++++++++--- en-US/Translation.xml | 2 +- en-US/U.xml | 21 ++++++++++++++++++--- en-US/WUG_References.xml | 7 ++++++- en-US/XYZ.xml | 7 ++++++- 15 files changed, 152 insertions(+), 38 deletions(-) diff --git a/en-US/Audience.xml b/en-US/Audience.xml index 9f3a48a..838fb69 100644 --- a/en-US/Audience.xml +++ b/en-US/Audience.xml @@ -17,8 +17,15 @@ 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 + 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 f0d1fd6..c09cfd3 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, 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 IBM Style, 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. @@ -315,7 +321,12 @@ breadcrumb, breadcrumb trail - Refer to IBM Style 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/C.xml b/en-US/C.xml index cefe0b9..bee0b62 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -63,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 section of IBM Style for more information. + For more information, refer to the Word Usage section of IBM Style + + + + + . @@ -159,7 +164,12 @@ - Refer to the Word Usage section of IBM Style for more information. + For more information, refer to the Word Usage section of IBM Style + + + + + . @@ -253,7 +263,13 @@ combo box - Do not use as an abbreviation for "combination box". Refer to the relevant entry in IBM Style 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 + + + + + . @@ -319,7 +335,12 @@ command line, command prompt, command-line - Refer to the appropriate entries in IBM Style for an explanation of how to use these terms. + For an explanation of how to use these terms, refer to the appropriate entries in IBM Style + + + + + . diff --git a/en-US/D.xml b/en-US/D.xml index 8e35148..ee4e3b3 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -23,7 +23,12 @@ dash - In technical publications, IBM Style recommends not to use em dashes. Use a colon or other suitable punctuation. + In technical publications, IBM Style + + + + + recommends not to use em dashes. Use a colon or other suitable punctuation. En dashes are used to show a range. Refer to Dashes in IBM Style diff --git a/en-US/Design.xml b/en-US/Design.xml index 7f9af52..9753ef7 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -783,10 +783,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 IBM Style and the Google Developer Documentation Style Guide. - - + Consider the following points when choosing a realistic name: @@ -819,6 +816,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. + @@ -1070,7 +1071,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest 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 - Capitalization in IBM Style + Capitalization in IBM Style diff --git a/en-US/F.xml b/en-US/F.xml index c3df6e2..eccdd6d 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -109,7 +109,13 @@ file mode, file name, file system, file type - n. Write as shown, two words, unless used as a variable. Refer to IBM Style 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/H.xml b/en-US/H.xml index 8f9e667..72342da 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -166,7 +166,12 @@ n. Usually one word. Capitalize the "H" at the beginning of a sentence. - Refer to IBM Style for more information. + For more information, refer to IBM Style + + + + + . diff --git a/en-US/I.xml b/en-US/I.xml index 4917042..51b532f 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -269,7 +269,12 @@ Intranet, intranet - Refer to the Word Usage section of IBM Style for guidance. + For guidance, refer to the Word Usage section of IBM Style + + + + + . diff --git a/en-US/New.xml b/en-US/New.xml index ff16b09..0fdc21e 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -116,7 +116,12 @@ Refer to . - Updated IBM Style access information. + Updated IBM Style + + + + + access information. Refer to . @@ -249,7 +254,12 @@ - Accessing IBM Style online. + Accessing IBM Style + + + + + online. Updated guidance for long commands. @@ -288,7 +298,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/Resources.xml b/en-US/Resources.xml index 475ebe9..b62d223 100644 --- a/en-US/Resources.xml +++ b/en-US/Resources.xml @@ -68,8 +68,8 @@ - IBM Style - + IBM Style + @@ -122,17 +122,20 @@ - The Chicago Manual of Style, 18th Edition. Chicago: The University of Chicago Press, 2024. + The Chicago Manual of Style + + + + + . The University of Chicago Press, latest version. + - Merriam-Webster Dictionary - - - Visit https://www.merriam-webster.com/ - + Merriam-Webster Dictionary. Merriam-Webster, latest version. +