search

StyleGuides / WritingStyleGuide

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

Add section on acronyms & abbreviations #239

Open sffrench opened 3 years ago

sffrench commented 3 years ago

Word nerds: acronyms & abbreviations - updated with more info, and added to the corporate style guide

Things we should add to this entry:

"acronyms & abbreviations Expand all acronyms and abbreviations on first use. Spell out acronyms or initializations before using them in text, e.g., ""Embedded DevKit (EDK)"", unless the acronym or initials stand for a proper noun, then use sentence case for the spelled-out version, e.g., ""central processing unit (CPU)"". Avoid using acronyms and abbreviations for product names. Refer to products by full name, as shown in the official Red Hat product and solution names list (Google docs). Do not use product acronyms in formal communications.

Exceptions: There are cases where acronyms and abbreviations are acceptable. These include:

After the first use in technical, customer-facing documentation. Examples: Getting started guides. Install guides. Documentation on the Customer Portal. Knowledgebase solutions and articles. Bugzilla entries. Support case summaries or details. Other subscription materials and resources. Training materials. When space is physically limited, such as: Very small web or print ads. Social media with a character or display limit (e.g. Twitter, Instagram). Products where the abbreviation or acronym is part of the official product name, including Red Hat AMQ. (In these cases, the abbreviation is more well-known than its expansion.)

Always ensure that the acronyms or abbreviations you use will not be confusing or conflict with other offerings or common terms.

To form the plural of an acronym, add a trailing, lowercase ""s"" with no apostrophe, e.g., ROMs, PINs, BIOSs.

Exception: Technical documentation uses ""es"" in some cases, for example, BIOSes, OSes, and similar terms."

daobrien commented 3 years ago

"Link to acronyms list that IC made on" ? I'm not sure what this means.

sffrench commented 3 years ago

I just copied this stuff from the word nerds spreadsheet, I am not sure either.

daobrien commented 3 years ago

A lot of the other content in the original issue is already in the RH Tech Writing Guide, although some bits might be missing. I can have a look and find them.

Note too that is not 100% accurate: "Expand all acronyms and abbreviations on first use." We don't expand common acronyms and abbreviations (RAM, HTTP, FTP) unless he happen to be explaining or teaching what they actually mean.

daobrien commented 3 years ago

This is marked as "Complete" in their spreadsheet, which is unfortunate, because it's incomplete. I can review our guide and make sure nothing is missing.