StyleGuides / WritingStyleGuide

The official Red Hat guide to writing clear, concise, and consistent technical documentation.
Creative Commons Attribution Share Alike 4.0 International
71 stars 19 forks source link

Restructure section 3.6 #505

Closed rclee33 closed 11 months ago

rclee33 commented 11 months ago

To strengthen clarity and cohesion, I suggest restructuring section 3.6 Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly. In the current version, the subsection on Acronyms includes guidance on Initialisms (in terms of article usage, spelling, pluralization, and capitalization). For clarity, I’d suggest first defining each category (abbreviations, acronyms, and initialisms) before providing the guidance on implementation (ex: article usage, spelling, pluralizing, and capitalization). I’ll add a suggested revision as a separate comment.

rclee33 commented 11 months ago

Suggested update for 3.6 (includes stylistic adjustments as well):

Abbreviations An abbreviation is a shortened form of a word or phrase. For example, Pty. and Inc. are abbreviations for "proprietary" and "incorporated", respectively. Read them as the word for which they are an abbreviation. ⁠ Acronyms An acronym is a word that is formed from the initial letters of a name, such as ROM for Read-Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol.

Initialisms An initialism is an abbreviation that consists of the first letters of words in a phrase, syllables, or some combination thereof. Each character is pronounced separately. For example, FTP is an initialism for File Transfer Protocol. Consider pronunciation when using articles. See Acronyms for more information.

Using Abbreviations, Acronyms, and Initialisms Correctly

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.

Capitalization: Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)". Not all acronyms are capitalized (for example, "spool"); see the IBM Style Guide or another suitable reference if you are unsure.

Articles: When deciding which articles to use, consider pronunciation. For example, "an RTS (real-time strategy)" uses “an” because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, "a RAM upgrade" uses “a” because RAM is an acronym and you pronounce it as a word (răm).

Plurals: To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes.

julian-cable commented 11 months ago

Adopting Rachel's proposal. The cross-reference for pronunciation to point to Articles.