Abbreviations and acronyms

Abbreviations and acronyms speed up reading for people who know them and create a wall for people who do not. The rules in this article ensure you get the benefit of brevity without the cost of confusion.

Define Acronyms on First Use

The first time an acronym appears in an article, spell out the full term and place the abbreviation in parentheses immediately after it. Use the abbreviation alone in all subsequent mentions within that article.

Example: "You can configure Single Sign-On (SSO) in the Security settings. Once SSO is enabled, users log in through your identity provider."

Do not assume a reader has read another article where the same acronym was defined. Each article is independently read. Define acronyms in every article where they appear.

If an acronym appears only once in an article, skip the parenthetical shorthand entirely and just use the full term. Defining an abbreviation you never use again adds clutter without saving the reader anything.

When Not to Define an Acronym

Some abbreviations are so universally known that spelling them out would feel patronizing to most readers. This list is not fixed — it depends on who the article is for.

By audience tier: an acronym safe to leave undefined for an advanced or developer audience may not be safe for a beginner audience. "API" can go undefined in API reference content aimed at developers, but should still be defined in a getting-started guide aimed at first-time, non-technical users. Scope this list to the specific article's audience, not to your product as a whole.

By visibility tier: internal (private) documentation can safely leave undefined any abbreviation your organization's staff universally knows — including internal team names, system names, or project codenames — that would never be safe to leave undefined in public-facing documentation. Public documentation should default to the more cautious, common-knowledge list below.

For a general, technically literate public audience, these typically do not need definition:

• HTML, CSS, PDF, URL, API, HTTP, HTTPS
• Common measurement abbreviations used in technical contexts: GB, MB, KB, ms
• Abbreviations that are more familiar than the full form: "FAQ" is better known than "Frequently Asked Questions"

The test: if this specific article's primary audience would almost universally recognize the abbreviation without help, you do not need to define it. If there is reasonable doubt, define it.

Creating New Abbreviations

Do not invent an abbreviation on the spot for convenience while writing. If you find yourself writing "KM" for knowledge management or any other unofficial shorthand you haven't seen used elsewhere, stop and write the full term instead. Ad hoc, in-the-moment abbreviations fragment your terminology, since no other article or writer will recognize them, and readers encountering them for the first time have nothing to anchor them to.

This is different from deliberately adopting a new, official abbreviation — which is a legitimate and normal part of a product's vocabulary evolving over time. If a term is used often enough that an abbreviation would genuinely help readers, propose it as an addition to your terminology or word usage glossary first, get it agreed on, and then use it consistently across the knowledge base going forward. The rule against invented abbreviations is about avoiding fragmentation from unilateral, undocumented shorthand — not about freezing your vocabulary permanently.

Abbreviations Versus Acronyms

The distinction matters for formatting:

• Acronyms are formed from the initial letters of a phrase and pronounced as a word: NATO, SCIM, WYSIWYG. Write these in all caps.
• Initialisms are formed from initial letters but pronounced letter by letter: URL, API, CSV. Write these in all caps.
• Abbreviations are shortened forms of a single word: Dr., Fig., etc. Use periods as described below.

Periods in abbreviations

• Traditional word abbreviations (Dr., Fig., vs., approx.) take a period.
• Acronyms and initialisms (API, SSO, CSV, URL) never take periods: not "A.P.I." or "U.R.L."
• Unit abbreviations (kg, ms, GB) never take periods: not "kg." or "ms."

See also: the Capitalization article covers how acronyms are capitalized once written; this section covers only when to use periods.

Latin Abbreviations

Avoid Latin abbreviations in documentation. They are less clear to readers for whom English is not a first language, and plain English alternatives exist for all of them.

Note on "etc.": beyond the translation problem, "etc." at the end of a list is a lazy shorthand that tells the reader nothing. Either complete the list or acknowledge you are giving examples: "for example, CSV, JSON, or XML."

Plurals of Abbreviations

Form the plural of an abbreviation by adding a lowercase "s" with no apostrophe.

Abbreviations in Headings

Avoid abbreviations in headings unless the abbreviated form is more widely known than the full form. If you do use an abbreviation in a heading, still define it on first use in the body text below.

Units of Measurement

Abbreviate units of measurement when they follow a numeral: "5 MB," "100 ms," "2 GB." Do not abbreviate when the unit is used without a number: "file size is measured in megabytes."

Do not add a plural "s" to abbreviated units: "5 MB" not "5 MBs."

Self-Audit Checklist

Before publishing, check abbreviations and acronyms against these questions:

• Is every acronym defined on first use in this article, regardless of whether it was defined elsewhere?
• If an acronym is used only once, has the parenthetical shorthand been skipped in favor of the full term?
• Is the "when not to define" judgment scoped to this article's actual audience tier and visibility (public/private), not a single fixed list?
• Is every abbreviation either an established, glossary-approved term or spelled out in full — with no ad hoc invented shorthand?
• Do acronyms and initialisms appear in all caps with no periods, and traditional abbreviations use periods correctly?
• Have Latin abbreviations (e.g., i.e., etc., vs., viz.) been replaced with plain English?
• Are abbreviation plurals formed with a lowercase "s" and no apostrophe?
• Are unit abbreviations used only alongside a numeral, without a trailing plural "s"?