These rules cover when to spell out an abbreviation, how to introduce it, and how abbreviations behave in running text. Pluralizing unit-of-measure abbreviations next to numbers is covered under pluralization.
abbr-001 should GuidesAPI docsMarketingBlog Spell out an abbreviation at its first use in a document, followed by the abbreviation in parentheses; use the abbreviation freely for subsequent mentions. Spelling out isn’t required for universal technical abbreviations (API, URL, HTTP, 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, while the short form keeps later mentions compact. Universal abbreviations and glossary terms don’t need expanding.
abbr-002 should GuidesAPI docsMarketingBlog Do not introduce an abbreviation in parentheses if it will appear only once in the document.
Examples
Rationale
Introducing an abbreviation you never reuse adds clutter without payoff.
abbr-003 should GuidesAPI docsMarketingBlog Lowercase the spelled-out form of an abbreviation unless it is a proper noun; do not capitalize it merely because the abbreviation uses capital letters.
Examples
Rationale
The letters being capitals in the abbreviation does not make the spelled-out words proper nouns.
abbr-004 should GuidesAPI docsMarketingBlog Do not abbreviate product or brand names.
Examples
Rationale
A brand name is a fixed identifier, so shortening it can be wrong or unrecognizable.
abbr-005 should GuidesAPI docsMarketingBlog Choose the article a or an based on the pronunciation of the abbreviation, not its spelling.
Examples
Rationale
The choice of a or an follows the spoken sound of the abbreviation, not its first letter.
abbr-006 should GuidesAPI docsMarketingBlog Form the plural of acronyms and abbreviations by adding a lowercase s with no apostrophe (APIs, DVDs).
Examples
Rationale
An apostrophe before the s reads as a possessive, not a plural; “APIs” is the plural.
abbr-007 should GuidesAPI docsMarketingBlog Do not use abbreviations as verbs.
Examples
Rationale
Using an abbreviation as a verb is informal and often unclear.
abbr-008 should GuidesAPI docsMarketingBlog Do not use periods with acronyms or initialisms.
Examples
Rationale
Periods in an acronym add noise and can break line wrapping, so modern usage omits them.
abbr-009 should GuidesAPI docsMarketingBlog Consider SEO needs when deciding whether to introduce an abbreviation in a heading or use it only once.
abbr-010 should GuidesAPI docsMarketingBlog Avoid internet slang abbreviations (tl;dr, RTFM, ymmv, fubar); write out the intended meaning in plain language.
Examples
--verify flag before every release build.--verify flag before every release build.Rationale
Slang abbreviations are not universally understood and read as unprofessional in documentation.
abbr-011 should GuidesAPI docsMarketingBlog Consider translation impact when deciding whether to spell out a term; spelled-out forms provide important context for human and machine translation.
Rationale
A spelled-out term gives translators and non-native readers the context an abbreviation hides.
abbr-012 should GuidesAPI docsMarketingBlog Maintain a list of well-known abbreviations that do not require spelling out (API, URL, USB, HTML, RAM).
Rationale
A shared list keeps authors consistent about which abbreviations can stand alone.