Abbreviations and Acronyms — Standards for Technical Documentation

In this tutorial, you will learn about Abbreviations and Acronyms. We cover key concepts, practical examples, and best practices to help you master this topic.

Abbreviations and acronyms save space and improve readability when used correctly. Used incorrectly, they confuse readers and create barriers to understanding. Clear rules for abbreviation usage ensure consistency across documentation.

In this lesson, you will learn how to handle abbreviations and acronyms in technical documentation.

What You'll Learn

You will understand when and how to use abbreviations, how to introduce them, and how to maintain an abbreviation list.

Why It Matters

Inconsistent abbreviation usage confuses readers. Expanding an acronym on every page but inconsistently, or using different abbreviations for the same term, creates unnecessary confusion.

Real-World Use

DodaTech maintains an abbreviation glossary with 200-plus entries. Vale rules enforce proper expansion on first use per page.

flowchart LR
  A[New Acronym] --> B{Is it well known?}
  B -->|Yes| C[Use without expansion]
  B -->|No| D[Expand on first use]
  D --> E[Use acronym thereafter]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Expansion Rules

Always expand an abbreviation or acronym on first use per page. After that, use the short form. Example: Network File System NFS becomes NFS after first use.

Some acronyms like HTML, CSS, API, and URL are widely known and do not need expansion. Use judgment based on your audience.

Create an abbreviation glossary if you use many abbreviations. New writers and readers can reference it.

# Correct abbreviation usage

The DodaZIP Compression Library DCL provides streaming compression.
Install DCL using pip. DCL supports gzip, bzip2, and xz formats.

# Well-known acronyms that do not need expansion
API, HTML, CSS, URL, JSON, XML, SQL

Articles and Plurals

Use a before consonant-sounding acronyms and an before vowel-sounding acronyms. A JSON parser, an XML parser.

Make acronyms plural by adding s without an apostrophe. API becomes APIs. URL becomes URLs.

Make acronyms possessive by adding apostrophe s. The API's response time. For plural possessives, APIs' response times.

# Article usage
- a JSON file (J sounds like consonant)
- an XML file (X sounds like vowel)
- a URL (U sounds like consonant)
- an API (A sounds like vowel)

# Plural forms
- One API, two APIs
- One URL, many URLs
- One OS, multiple OSes

Common Mistakes

1. Expanding on Every Page

Expanding the same acronym on every page is unnecessary. Expand once per page.

2. Creating Unnecessary Acronyms

Creating an acronym used only once. If you use it only once, write the full term.

3. Inconsistent Expansion

Expanding on some pages but not others. Use a consistent policy.

4. Wrong Article

A API instead of An API. Listen to the pronunciation of the acronym.

5. Apostrophe in Plurals

API's when meaning multiple APIs. The apostrophe indicates possession, not plurality.

6. No Glossary

Using many acronyms without a glossary. Provide a reference for readers.

7. Assuming Universal Knowledge

Using acronyms that are well known in your field but unknown to your audience.

Practice Questions

1. When should you expand an acronym?

On first use per page. Write the full term followed by the acronym in parentheses.

2. Which acronyms do not need expansion?

Well-known acronyms like HTML, CSS, API, and URL. Use judgment based on audience.

3. How do you make an acronym plural?

Add s without an apostrophe. API becomes APIs.

4. How do you choose a or an for an acronym?

Based on pronunciation. A before consonant sounds, an before vowel sounds.

5. Challenge: Create an abbreviation glossary for a project with at least 20 entries. Include the abbreviation, full form, and a usage note for each.

FAQ

Mini Project

Audit a documentation set for abbreviation issues. Find five acronyms used without expansion, three inconsistent expansions, and two incorrect article usages. Create a glossary entry for each and fix the issues.

What's Next

Next: Capitalization Rules