Abbreviations save space, but unfamiliar or unnecessary short forms slow readers down. Use this page to decide when to spell out an abbreviation and how to use its short form in body text.
For more information about pluralizing a unit-of-measure abbreviation next to a number, see pluralization.
abbr-001 should GuidesAPI docsMarketingBlog Spell out an abbreviation at its first use in a document, followed by the abbreviation in parentheses. After that, use the abbreviation. You don’t need to spell out widely recognized technical abbreviations such as API, URL, HTTP, and JSON, abbreviations defined in a glossary, or abbreviations more familiar than their expansions.
Examples
Rationale
Spelling out an abbreviation on first use lets a reader who doesn’t know it follow along, and the abbreviation keeps the rest of the document short.
abbr-002 should GuidesAPI docsMarketingBlog Don’t introduce an abbreviation in parentheses if it appears only once in the document.
Examples
Rationale
An abbreviation that appears once gives the reader a second form to remember and never saves any space.
abbr-003 should GuidesAPI docsMarketingBlog Lowercase the spelled-out form of an abbreviation unless it’s a proper noun. Don’t capitalize it because the abbreviation uses capital letters.
Examples
Rationale
Capital letters in the abbreviation don’t make the spelled-out words proper nouns.
abbr-004 should GuidesAPI docsMarketingBlog Don’t abbreviate product or brand names.
Examples
Rationale
A brand name is a fixed identifier. A shortened form can be incorrect or unfamiliar to readers.
abbr-005 should GuidesAPI docsMarketingBlog Choose the article a or an by the pronunciation of the abbreviation, not its spelling.
Examples
Rationale
The letter H in HTML is pronounced with an initial vowel sound, so HTML takes an. The article follows the sound, even when the written abbreviation begins with a consonant.
abbr-006 should GuidesAPI docsMarketingBlog Form the plural of an acronym or abbreviation by adding a lowercase s with no apostrophe: APIs, DVDs.
Examples
Rationale
An apostrophe before the s normally marks a possessive or contraction, not a plural.
abbr-007 should GuidesAPI docsMarketingBlog Don’t use abbreviations as verbs.
Examples
Rationale
An abbreviation used as a verb can hide the intended action. Naming the action, as in connect over SSH, is clearer and easier to translate.
abbr-008 should GuidesAPI docsMarketingBlog Don’t use periods with acronyms or initialisms.
Examples
Rationale
Periods make an acronym longer and harder to scan, and a period inside the acronym can be mistaken for the end of a sentence.
abbr-009 should GuidesAPI docsMarketingBlog Consider search engine optimization when you decide whether to introduce an abbreviation in a heading or to use it only once (abbr-002).
Rationale
Readers search for the form they know, which can be the abbreviation or the spelled-out term. A heading or first paragraph that contains that form is easier to find.
abbr-010 should GuidesAPI docsMarketingBlog Don’t use internet slang abbreviations such as tl;dr, RTFM, ymmv, or fubar. Write the meaning in plain language.
Examples
--verify flag before every release build.--verify flag before every release build.Rationale
Slang abbreviations aren’t understood everywhere and can be difficult to translate. Some, such as RTFM, are also rude.
abbr-011 should GuidesAPI docsMarketingBlog Consider translation when you decide whether to spell out a term. A spelled-out form gives human and machine translators context that an abbreviation hides.
Rationale
An abbreviation can have no equivalent, or a different meaning, in the target language. The spelled-out term helps a translator choose an accurate form.
abbr-012 should GuidesAPI docsMarketingBlog Keep a list of the abbreviations that abbr-001 exempts from spelling out, such as API, URL, USB, HTML, and RAM.
Rationale
A shared list gives every author the same exceptions and avoids deciding the same question on each page.