Abbreviations are any shortened or contracted word or phrase. For example, writing St. instead of Street, or Rx for prescription, or OKC for Oklahoma City.

Acronyms are a type of abbreviation. They shorten phrases in a specific way— using parts of the initial word or phrase (usually letters) to form an abbreviation. For example, DIY or ASAP.

In the most technical sense, there is a difference between acronyms (abbreviations pronounced as words, like NASA) and initialisms (abbreviations pronounced as letters, like FBI). For simplicity, our content guide refers to both as acronyms. The readability issues that acronyms and initialisms create tend to be similar, and “acronym” is the more common term.

Acronyms often confuse readers. Avoid them whenever possible.

If an acronym is necessary for future reference, spell the full word and follow with the acronym in parentheses on the first reference. For example, The General Services Administration (GSA).

Some acronyms are more recognizable than their full spellings. For example, NASA, NAACP, FBI. In such instances, the acronym is always acceptable, at the writer’s discretion.

At the writer’s discretion, refer to organizations on second reference with a shortened name instead of an acronym. For example, use Labor in place of Department of Labor, rather than DOL.

Active voice

Our writing should be concise and direct. We prefer the active voice because it supports brevity and makes written content more engaging, too.

The active voice helps the reader identify the subject of the sentence. In the following example, the person who submits the form is essential information. Omitting that leads to a confusing and impersonal sentence.

Passive: The request form must be submitted to the approving official.
Active: You must submit the request form to the approving official.

Along with deemphasizing who should take an action, the passive voice is usually longer, too. Wordy instructions are harder to follow.

Passive: The case number should be saved in your records. It will be required for future inquiries.
Active: Save the case number in your records. You will need it for future inquiries.

When in doubt, cut directly to the verb and give the reader clear directions.

How to recognize the passive voice

Use of the passive voice is common enough that many people don’t notice when they use it. Here’s a simple way to recognize it. If you insert “by zombies” after the verb and the sentence still makes sense, you’re using the passive voice.

When to use the passive voice

Never use the passive voice in a way that makes actions seem like they happen without anyone doing them.

You may occasionally need to use the passive voice to soften an error message or make something easier to understand.

Rewording either of these sentences to use the active voice would complicate the sentence or pull focus away from its main point:

Example: The agency is required to respond to requests within 20 working days.

Follow a consistent capitalization scheme.

Creating trustworthy internal and external communications relies, to a large extent, on the content’s consistency. Inconsistent spellings and capitalizations undermine your narrative authority. We follow these capitalization guidelines:

• Do capitalize proper nouns, including names of individuals, places and agencies
• Don't capitalize agile, unless it is the first word of a sentence
• Don't capitalize open source, unless it is the first word of a sentence
• Don't capitalize federal or government

When you're deciding whether to capitalize noun phrases, keep in mind that in English, title case is often a marker of formality. Using it judiciously can help clarify that you're speaking about a specific, official thing (such as a form, office, or person). Overuse can cause users stress by implying formality or officialness where it doesn't exist. For instance:

• It makes sense to capitalize the phrase Form 1040, U.S. Individual Income Tax Return because you want users to know the exact, official title of that specific form.
• It could confuse users to capitalize income taxes or income tax forms, because those phrases could refer to any number of possible forms.

Personal titles

Don’t capitalize personal titles unless they precede a name. For example, the director got approval or Director Lopez got approval. Whenever possible, keep titles gender neutral. For example, we prefer firefighter to fireman and chairperson to chairman.

Headings

Headlines, page titles, subheads and similar content should follow sentence case, and should not include a trailing colon. For example:

Making sense of Washington’s tech landscape

Privileges and responsibilities

Inclusive language

The words we use can make the difference between forging positive connections or creating distance in our personal and professional lives. Particularly in writing, impact is more important than intent.

As we build government services, we want to ensure they are accessible and welcoming to everyone who needs to use them. Inclusive language helps us to be more accurate and build trust with our users.

This guidance is influenced by the Conscious Style Guide, which is an excellent resource for learning more about the conversations behind terms, categories and concepts. Other resources we used:

• Diversity Style Guide
• Disability Language Style Guide
• Associated Press Stylebook
• Syracuse University Disability Cultural Center Language Guide

This page is not exhaustive, but aims to provide principles, resources and specific suggestions for writing and talking about diverse groups of people.

Ability and disability

Every person is a whole person — no matter how they interact with the world. Focus on what they need to do, what tools they use, and avoid making assumptions. If a person’s situation, medical condition, illness, or injury is relevant to the content, be as specific as possible and avoid inserting value judgements about their circumstance (for example, use has multiple sclerosis, not is afflicted with or suffers from).

Just like with language around race, gender, or other identities, it’s always best to ask people how they identify rather than assuming. For help finding appropriate or accurate language, see the Disability Language Style Guide from the National Center on Disability and Journalism.

• Avoid describing people as disabled, handicapped or confined to a wheelchair.
• Avoid terms that contribute to stigmas around disability or mental illness: crazy, dumb, lame, insane, psycho, schizophrenic or stupid.
• Avoid terms that contribute to stigmas around sensory disabilities: blind spot or tone deaf.

Age

Avoid referring to someone’s age, unless it’s relevant to what you're writing about (for example, when referring to benefits that are available to people of certain ages).

• Don’t use women or older relatives as substitute for novice or beginner. For example, don’t say something is so simple your mother can use it.
• We prefer older person or senior to elderly.

Gender and sexuality

Make content gender-neutral wherever possible, and strive to write in a gender-fair way. If you’re writing about a hypothetical person or if you’re unsure of the person’s pronouns, use they or them instead of he/she.

Avoid words and phrases that indicate gender bias, such as irrelevant descriptions of appearance.

Use descriptors of gender identity or sexual orientation as modifiers, not as nouns (for example, transgender person, cisgender person, or lesbian woman). Avoid guessing sex, gender identity, or sexual orientation. When in doubt, either reconsider the need to include this information or ask the person you’re referring to how they identify and what terms they prefer.

• Use different sex instead of opposite sex (because this recognizes gender as a spectrum, rather than a binary).
• We support using they or their as singular pronouns.
• Avoid guys as a way to refer to mixed-gender groups.
• Don't make assumptions about marital or family relationships (for example, use spouse or partner instead of husband and wife; use parent instead of mother and father).

For more detailed guidance, see the National Lesbian and Gay Journalists Association Style Guide or the GLAAD Media Reference Guide.

Nationality

Avoid using citizen as a generic term for people who live in the United States. Many government programs serve non-citizens and individuals with a wide range of immigration and visa statuses.

• How you refer to the public is largely dependent on context. Feel free to choose from any of these words: people, the public, users or folks.
• Be as specific as possible. Depending on the situation, you may want to say something like people who need healthcare or people who need to access government services online.
• Use citizens for information related to U.S. citizenship, for example, when describing who is eligible to vote in federal elections.
• Be careful with Americans or the American public. These terms are ambiguous and are often used as synonyms for citizens. In most cases, the public is equally clear and more inclusive. That said, referring to Americans or the American people can be useful if you want to inspire readers or take a more patriotic tone.

Race, ethnicity and religion

Avoid using words, images or situations that reinforce racial, ethnic, or religious stereotypes (even stereotypes that may appear to be positive). Avoid the term non-white, or other terms that treat whiteness as a default.

Don’t make assumptions: ask how people identify themselves, and be aware of complexities within racial, ethnic and religious identities. For example, not all Arabs are Muslim, and many nationalities and ethnicities include various religious practices and traditions.

When referring to a person’s race or ethnicity, use adjectives, not nouns (for example, a Hispanic person, not a Hispanic).

Media style guides for race, ethnicity and religion

• National Association of Black Journalists Style Guide
• Guidance from the Asian American Journalists Association
• Native American Journalists Association Reporter's Indigenous Terminology Guide
• Religion Newswriters Association's Religion Stylebook

Personal names

Use full names on first reference. On second reference, use first names when writing about our teams or our work, and otherwise follow AP style (which is to mostly use last names on second reference).

If the context means that there’s a chance of confusion on second reference when using only first or last names, use full names.

State names

• Spell out state names, such as Oklahoma.
• When referring to a number of states, “state” should be lowercase. For example, All 50 states responded.
• When used with a city, spell out the name of the state. For example, Atlanta, Georgia.

Numbers

Generally speaking, we follow the guidelines outlined in the AP Stylebook. In body copy, we prefer to spell out numbers one through nine, and use numerals for numbers 10 and greater. This is true of ordinal numbers, as well. Spell out first to ninth, and capture 10th or greater with numerals.

Sometimes the government writes about very large numbers: millions, billions, even trillions. We express these numbers with a numeral and a word. For example, 1.6 million people. When referring to amounts of money in cents or greater than $1 million, we use numerals followed by words: 5 cents or $2.7 million. For amounts of money less than $1 million, we use the dollar sign: $17.

In titles, subheadings, and interface labels, we use numerals instead of spelling out numbers. For example, 10 digital tech leaders you should know now or 6 ways to incorporate plain-language strategies. We do this to promote ease of reading and scannability — in titles and headings, it’s easier for readers to scan numerals than it is for them to scan written-out numbers.

Percentages

In keeping with AP style, we spell out percent in most cases, with a few exceptions. We use the percent sign (%) in these circumstances:

• Tables and in technical or scientific writing. For example: 60% of participants reported experiencing negative side effects.
• Headings and subheadings. For example: Candidate Woof takes 7% lead in the election for best dog.
• Interface labels
• Captions and infographics

We choose to use the percent sign in these cases to improve content’s scannability, allowing readers to digest the content more quickly.

Dates

To avoid confusion, we spell out specific dates such as "October 22, 2005," rather than abbreviating the month or using numbers as in "10/22/2005." Use the full, four-digit year. For informal writing, it's okay to use an abbreviated form. For example, We're thankful web design isn't stuck in the '90s.

Bulleted lists

Capitalize the first word of every bullet. Don't use semicolons after points in a bulleted list. Include a period at the end of the bullet only if that point is a complete sentence. For example:

When you go to the store, please buy:

• Apples
• Bananas
• Naan chips

When you leave the house:

• Please buy apples, bananas, and naan chips.
• Fill the car with gas.
  

Colons

Capitalize the first word after a colon, only if what follows is a complete sentence. For example:

I have several favorite foods: apples, bananas, and naan chips.

I have several favorite foods: Apples were my first favorite snack, but naan chips are a rising star in my life.

Dashes

When offsetting a phrase with dashes you should use the longer em dash (—), which is Option + Shift + - on Macs, with a space on either side of the dash. For example:

We emphasize open, digital record keeping, and — whenever possible — we illuminate our processes.

Although we advocate using words rather than symbols, in some contexts you may use an en dash to convey a range of numbers. For example, both 10–20 students and 10 to 20 students are acceptable options. En dash is Option + - on Macs.

We assign 2–3 people to each development team.

Quotes

These quotations are correctly punctuated:

“Would you like a banana?” he asked.

“I hate bananas,” she said. “You know I hate bananas.”

He paused before saying “bananas are not something people should hate.”

Spaces

Sentences should always be separated by a single space. Never two spaces.

Ampersands or plus signs

Use and instead of an ampersand or plus sign, unless they’re part of an official title or company name.

Slashes

Avoid using the slash / symbol. Replace it with words or commas as appropriate.

Trademarks and brands

Avoid using a trademark unless you’re referring to a specific product.

This can be tricky when a trademarked name, like Kleenex, has become synonymous with an entire family of products. Try to use a generic word — like tissue — instead of a brand name.

Common trademarked words (with alternative terms)

• Band-Aid (adhesive bandage, bandage)
• Bubble Wrap (packaging bubbles)
• Chapstick (lip balm)
• Crayola (crayons)
• Dumpster (waste container, trash container)
• Hi-Liter (highlighting marker)
• iPod (MP3 player)
• Kleenex (tissue)
• Plexiglas (plastic glass)
• Post-it note (adhesive note)
• Q-Tips (cotton swabs)
• Scotch tape (transparent tape)
• Styrofoam (plastic foam)
• Taser (stun gun)
• Xerox (photocopy, copy)

Guidelines

Careful use of trademarked names and brands is important because the government shouldn’t endorse specific brands or products. When writing about corporate brands or products to illustrate a point, mention a range of related companies instead of a single provider. For example:

Twitter, Facebook and YouTube can help you connect with users.

Avoid linking to products or services, because people can see it as an endorsement. The same rule applies to the brands and products of individuals, such as personal websites or websites where you can buy their book.

Creating URLs

URLs should be short, memorable, easy to type and well-structured. Your control over your URL may be limited, but you should do what you can with the pieces you can control.

In the vast majority of cases, everything a user can reach on your site should have a distinct URL that a user can bookmark and use later to reach that same location.

When creating URLs, use dashes to separate words, omit articles (a/an/the), use the stems of verbs (/make-thing/ rather than /making-thing/), and avoid extraneous terms.

Paths

Again, the shorter the better, but long paths are more excusable than long domains.

Paths are typically understood as hierarchies that become increasingly specific: /our-style/urls-and-filenames/ reflects that urls-and-filenames is part of our-style. If this were a much larger guide, it’s possible that it could be divided further, for example /our-style/urls-and-filenames/creating-urls/.

Maintaining URLs

Users constantly bookmark and share web pages, making the maintenance of permanent and long-lasting URLs an important piece of content management. Broken links obscure the internet landscape.

URLs should never stop working.

This is not as technically challenging as it sounds. If the domain — the high-level domain, not subdomains — is lost, the URLs will be lost, but otherwise it’s entirely possible to keep them working. Planning for them to continue working is the first step in any process that involves new URLs.

Whenever possible, maintain original URLs. In all other cases, set up a redirect for outdated URLs and links; this is almost always a painless task for web managers. There are a variety of ways to accomplish this, some of them requiring more technical work than others.

Creating filenames

Use hyphens to separate words, just as with URLs.

Lowercase is better, because it’s easier to type and to remember.

Use the right extension — PDFs should have .pdf at the end, JPGs should have .jpg at the end, etc.

Shorter is better, but the content should be descriptive to the user, and it’s better to have long descriptive filenames than short obscure ones. summary-of-pay-gap-findings.pdf is better than paygap.pdf or smmrypgpfnds.pdf.

If the file content is based on a date or time, include that: the 1998 report for an organization should have 1998 in the filename, a February issue of a magazine should have the year and the month, and a PDF of a daily newspaper should have year, month, and date. When including dates, use the YYYY-MM-DD format, i.e. 2015-10-13.

Avoid the use of special characters beyond the hyphen and period, unless absolutely necessary. Do not include spaces (use hyphens in their place).

Presenting URLs and filenames in text

Whether beginning with the protocol or not, always lowercase URLs in text. Paths are case-sensitive, however, so their casing must be preserved.

In interactive contexts, particularly web pages, URLs (except when used as examples, as throughout this document) should always be active links. When they’re active links, do not include the protocol in the link text.

In non-interactive contexts, such as print, the protocol can be omitted, assuming http:// and https:// both work and bring the user to the same place.

There are occasions where URLs should be delimited; use < and > for this. This is not normally necessary in interactive contexts where the link is clearly defined, but is most often relevant in email, where the writer may have to guess at what their email program will turn into a link. This is particularly true when URL contains spaces.

Filenames are case-sensitive, and their case should be preserved when they are referred to in text; do not capitalize if beginning a sentence with a filename that begins with a lowercase letter. Filenames may need to be delimited in the same way as URLs.

Link text

It’s important to remember that users of screen readers will often skip from one link to another, skipping the text in between, as a way of skimming for the content they need.

This ultimately means that link text should be understandable independent of the text surrounding it. Avoid ambiguous link text like click here, here, or learn more whenever possible.

For example, instead of:

Click here for more information about our Code of Conduct.

Use:

For more information, see the OKC Code of Conduct.

This has an added benefit of improving search results for sighted users.