diff --git a/README.md b/README.md index 85a0d78..5c95deb 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ WritingStyleGuide ================= -A guide to writing clear, concise, and consistent technical documentation. +This guide is the official style guide for Red Hat training and certification content, and for all other technical documentation except as stated. +Red Hat product documentation by Customer Content Services (CCS) follows the Red Hat supplementary style guide at https://redhat-documentation.github.io/supplementary-style-guide/ instead of this Red Hat Technical Writing Style Guide. -The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat. +The Red Hat Technical Writing Style Guide includes everyday punctuation and grammar, common mistakes to avoid, strategies for translation and global audiences, and a word usage dictionary. -It covers recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases. +This guide is a public guide. It is reviewed and maintained by Red Hat. Contributions from the wider community are always welcomed. -It is based on The IBM Style Guide but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions. +Other resources for technical writing are listed in the "Resources" section of the guide. Dependencies: @@ -15,7 +16,7 @@ Dependencies: $ sudo dnf install publican ``` -Also, follow the instructions at https://github.com/RedHatTraining/redhat-styleguide-xsl (access for Red Hat only) to build `publican-brand-redhat-*.noarch.rpm` and install that. +Also, follow the instructions at https://github.com/RedHatTraining/redhat-styleguide-xsl (access for Red Hat only) to build `publican-brand-redhat-*.noarch.rpm` and install that. To build: diff --git a/en-US/Audience.xml b/en-US/Audience.xml index 4e63d5f..838fb69 100644 --- a/en-US/Audience.xml +++ b/en-US/Audience.xml @@ -17,6 +17,20 @@ Other resources for technical writing are listed in . + Of these resources, + IBM Style + + + + + + is available for Red Hat employees to access online, but does not have a wider circulation. + Links in this guide to IBM Style are denoted by a padlock icon + + + + + . diff --git a/en-US/B.xml b/en-US/B.xml index b72d4c5..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, 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/C.xml b/en-US/C.xml index d771def..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 chapter of the IBM Style Guide for more information. + For more information, refer to the Word Usage section of IBM Style + + + + + . @@ -159,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 + + + + + . @@ -250,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 + + + + + . @@ -319,7 +335,12 @@ 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. + 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 206a541..ee4e3b3 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -23,7 +23,19 @@ 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 + + + + + . @@ -35,13 +47,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 +74,13 @@ n. Use the two-word form. - + @@ -230,7 +242,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 4f28c84..9753ef7 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 @@ -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. @@ -766,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 the IBM Style Guide and the Google Developer Documentation Style Guide. - - + Consider the following points when choosing a realistic name: @@ -802,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. + @@ -1052,7 +1070,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..eccdd6d 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -94,7 +94,12 @@ file extensions (general usage) - Refer to File names, file types, and directory names in the IBM Style Guide. + Refer to Files and Directories in IBM Style + + + + + . @@ -104,7 +109,13 @@ file mode, file name, file system, file type - n. Write as shown, two words, unless used as a variable. Refer to the IBM Style Guide for more information. + n. Write as shown, two words, unless used as a variable. + For more information, refer to IBM Style + + + + + . adj. Hyphenate when used as a compound adjective. For example, "file-system attributes". diff --git a/en-US/G.xml b/en-US/G.xml index 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..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 the IBM Style Guide for more information. + For more information, refer to IBM Style + + + + + . diff --git a/en-US/I.xml b/en-US/I.xml index 9b603c5..51b532f 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -269,7 +269,12 @@ Intranet, intranet - Refer to the "Word usage" appendix of the IBM Style Guide for guidance. + For guidance, refer to the Word Usage section of IBM Style + + + + + . diff --git a/en-US/K.xml b/en-US/K.xml index 6ab0f29..b3483fb 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -10,7 +10,12 @@ KB, kB - Refer to the IBM Style Guide for the correct abbreviation to use for specific use cases. + For the correct abbreviation to use for specific use cases, refer to Units of Measurement in IBM Style + + + + + . diff --git a/en-US/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/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/Punctuation.xml b/en-US/Punctuation.xml index 841e9cc..bb62e9d 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 + + + + + .
diff --git a/en-US/Resources.xml b/en-US/Resources.xml index d07160f..b62d223 100644 --- a/en-US/Resources.xml +++ b/en-US/Resources.xml @@ -6,38 +6,56 @@ Resources - This section lists some books and websites for you to consult on your quest to create a better document. + This section lists some helpful resources for creating effective technical content. - The guides that you refer to first are generally dictated by the type of material that you are writing. It is important to establish this point first because the guidelines in the following references sometimes contradict each other. It does not mean that the guidelines are wrong; different audiences require different writing styles, and different references are sometimes required when you change styles. The following documentation types are recognized: + The type of content that you are writing will determine which resources are most relevant. + In general, consult company-specific style guides before general resources. + The guidelines in the following references sometimes contradict each other. + It does not mean that the guidelines are wrong; rather, different audiences and genres require different writing styles, and different references are sometimes required when you change styles. + + + The following technical content types are within the scope of this guide: - Technical content: software manuals and documentation, user guides, training courses + Software manuals and documentation - + - Technical collateral: white papers and technology briefs + Training courses - + - Marketing content: advertising, promotions, articles + User guides + + + White papers + + + + + + + + The following content types are outside the scope of this guide: + - Corporate collateral: related to company or products + Marketing content: advertising, articles, press releases, promotions - Press releases + Corporate content about the company or its products @@ -46,14 +64,27 @@
- References for Technical Content and Collateral + References for Technical Content - IBM Style Guide. IBM Corporation, latest version. - - - Red Hat employees can now access the latest version of the IBM Style Guide online, at https://www.ibm.com/docs/en/ibm-style/. + IBM Style + + + + + . + IBM Corporation, latest version. + + + Red Hat employees can access the latest version of IBM Style online, at https://www.ibm.com/docs/en/ibm-style/. + IBM Style does not have a wider circulation. + Links in this guide to IBM Style are denoted by a padlock icon + + + + + .
-
+ + diff --git a/en-US/Translation.xml b/en-US/Translation.xml index b12d4ba..1637373 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 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. diff --git a/en-US/U.xml b/en-US/U.xml index a1ebb01..b37e156 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -48,7 +48,7 @@ uninterruptible - adj. Despite not appearing in the American Heritage Dictionary, this term does appear in the Merriam-Webster Unabridged Dictionary, and is considered acceptable in Red Hat documentation, especially in the context of "uninterruptible power supply (UPS)". + adj. This term appears in the Merriam-Webster Dictionary, and is considered acceptable in Red Hat documentation, especially in the context of "uninterruptible power supply (UPS)". @@ -94,7 +94,12 @@ v. Do not use. - Refer to the Word Usage chapter of the IBM Style Guide. + Refer to the Word Usage section of IBM Style + + + + + . @@ -115,7 +120,12 @@ v. Do not use. - Refer to the Word Usage chapter of the IBM Style Guide. + Refer to the Word Usage section of IBM Style + + + + + . @@ -141,7 +151,7 @@ - + upstream @@ -231,7 +241,12 @@ n. Usually one word. Capitalize the "U" at the beginning of a sentence. - Refer to the IBM Style Guide for more information. + For more information, refer to IBM Style + + + + + . diff --git a/en-US/WUG_References.xml b/en-US/WUG_References.xml index 364183d..dc968e5 100644 --- a/en-US/WUG_References.xml +++ b/en-US/WUG_References.xml @@ -6,13 +6,18 @@ References - the IBM Style Guide + IBM Style + + + + + - Chicago Manual of Style, 17th Edition + Chicago Manual of Style, 18th Edition - American Heritage Dictionary + Merriam-Webster Dictionary diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index 48dd375..3b0832e 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -138,7 +138,12 @@ v. Do not use. - Refer to the Word Usage chapter of the IBM Style Guide. + Refer to the Word Usage section of IBM Style + + + + + . diff --git a/en-US/images/padlock.png b/en-US/images/padlock.png new file mode 100644 index 0000000..2b82af2 Binary files /dev/null and b/en-US/images/padlock.png differ