Print

If a print dialog doesn’t appear, please select File → print from your browser.

How to use this guide

This guide was developed for 18F employees, but we hope it’s a useful reference for anyone.

Introduction

This guide helps writers create content that’s easy to understand and meets people where they are. Government websites often talk at readers rather than to or with them. As with other facets of its online presence, .gov writing tends to describe the government’s concerns in “governmentese,” leaving users frustrated by information that is neither actionable nor understandable.

This guide takes that frustration into account, as well as several commonly supported guidelines about writing for the web. Using this guide can help content designers benefit from our experience to date, incorporate user feedback into the editorial process, and build trust by communicating in a consistent manner.

If you work at 18F

We created this guide for reference on an as-needed basis. It’s here when you’re wondering whether to capitalize the word federal, for instance, or when you’re wondering how to create a friendly, informational tone.

To this end, we’ve structured the guide into descriptively named sections. Find the topic you’re looking for in our table of contents, or search by keyword. We aren’t opposed if you’d like to read this guide start to finish, of course.

If you have any suggestions or want to get involved, please chat us in #g-content or create an issue in GitHub.

If you work at another organization

As a work of the federal government, this project is in the public domain within the United States. Additionally, we waive copyright and related rights in the work worldwide through the CC0 1.0 Universal public domain dedication.

We encourage you to make a copy of this guide and adapt it to your organizational needs. This guide is just that: a guide. It’s not meant to provide the final opinion on any of the topics discussed. If a certain section isn’t relevant to you and your team, delete it. And if you feel the guide is missing a section, by all means, add it. This guide is yours to use, and we trust you’ll update it in the ways that best suit you.

Resources

We adapted this guide from GOV.UK’s work, and we’d like to thank their content team for championing plain language and information accessibility.

Style guides

We generally follow AP style unless otherwise noted.

As we created this guide, we also referred to these resources:

Content principles

Start with user needs.

Write in a way that suits the situation. Ask yourself: Who is going to read this? What do they need to know? How might they be feeling?

Help people find the information they need quickly and easily. Guide them through the process.

Do the hard work to make it simple.

Use plain language and simple sentences.

Choose clarity over cleverness.

Write for everyone.

Respect the complexity of our users’ experiences.

Be willing to be surprised about who’s reading your work.

Build trust.

Talk like a person.

Tell the truth.

Use positive language and concrete examples.

Start small and iterate.

Make sure your content works for users. Don’t be afraid to scrap what’s there and start over.

Write a draft, test it out, gather feedback, and keep refining.


We drew from multiple sources to develop this. Thanks to GDS, MailChimp, and Facebook for inspiration.

Address the user

Content on government sites often makes a direct appeal to the public to get involved or take action.

Address the user as you whenever possible. For example:

You can email us at 18F@gsa.gov or find us on Twitter.

Learn more about starting your MyRA account.

If you’re creating content for multiple users—such as patients and their caregivers—address the primary user as you and refer to secondary users by their roles or titles.

We recommend against using the word citizens when talking about the public. See the conscious style section for further guidance.

Avoid duplication

If something is written once and links to relevant information easily and well, people are more likely to trust the content. Duplicate content produces poor search results, confuses the user, and damages the credibility of our websites.

If users can find two similar pieces of content on a subject, they might end up calling a helpline or sending an email to the first address they find because they aren’t sure they have the right information.

There are thousands of federal websites. Collectively, they host hundreds of millions of pieces of content. What are you writing about? What are other agencies publishing? Are users across the country and the world seeing a coherent view?

Before you publish something, check that the user need you’re trying to address has not already been covered:

  • Search for the content using a popular search engine like Google or Bing. This is how most users will start, too. If content is already easy to find, duplicating it can lead us to compete with ourselves for search results.

  • Often, 18F team members write about a government service, tool, or program. Think authoritatively: What department or agency controls the thing you’re writing about? What information have they produced already?

  • Start significant projects with a content audit. Identify how any existing information is used and whether it will be helpful to your users in its current state. If it isn’t, what must change for it to help you address your users’ needs? Focus your work on those changes.

Be concise

To keep content understandable, concise, and relevant, it should be:

  • Specific
  • Informative
  • Clear and concise
  • Brisk but not terse
  • Incisive (friendliness can lead to a lack of precision and unnecessary words) but human (not something generated by a faceless machine)
  • Serious but not pompous or emotionless—adjectives can be subjective and make the text sound more emotive and like spin

You should:

  • Use contractions (such as can’t and won’t)
  • Not let caveats dictate unwieldy grammar (for example, say You can rather than You may be able to)
  • Use the language people are using
  • Use Google Trends to check for common search terms
  • Use short sentences
  • Check sentences with more than 25 words to see if you can split them for clarity

Words ending in –ion and -ment tend to make sentences longer and more complicated than necessary. Avoid turning verbs into nouns, a common sign of governmentese at work.

Keep sentences short and sweet

Craft sentences at 25 words or fewer, whenever possible. If a sentence has fewer than 14 words, readers understand 90 percent of content. At 25 words, sentences are markedly more difficult to comprehend.

We also recommend varying sentence length. Switching things up helps you keep readers interested. This tactic will also give you better control of your content’s tone — a text with only short sentences can unintentionally sound terse. The occasional longer sentence adds a bit of narrative interest (and can help a piece of writing sound friendlier, too).

Here’s an example of how you might transform a too-long sentence into something more manageable. Instead of:

Due to privacy and logistical considerations, passes cannot be replaced if lost or stolen; a new Paper Voucher must be accessed by going to the everykidinapark.gov website and completing the same activities to obtain a new Paper Voucher.

Use:

Unfortunately, we can’t replace lost or stolen passes. Get a new pass by visiting everykidinapark.gov and signing up again.


Thanks to GDS, who we looked to for inspiration when writing this page.

Use plain language

U.S. government websites are for everyone. The content they contain should be as straightforward as possible.

One of the best ways to make content clear and usable is to use plain language. When we use words people understand, our content is more findable, accessible, and inclusive. Plain language is also mandatory for all federal government websites.

When we use jargon in our writing, we risk losing users’ trust. Government, legal, business jargon are often vague or unfamiliar to users, and can lead to misinterpretation.

Another temptation that can hurt readability is figurative language: it often doesn’t say what you actually mean, and can make your content more difficult to understand. For example:

  • drive (you can only drive vehicles, not schemes or people)
  • drive out (unless it’s cattle)
  • going forward (unless you’re giving directions)
  • one-stop shop (we’re the government, not a big box store)

In most cases, you can avoid these figures of speech by describing what you’re actually doing. Be open and specific.

If you’re struggling to use plain language, try writing conversationally. Picture your audience and write as if you were talking to them one-on-one, with the authority of someone who can actively help.

Don’t use formal or long words when easy or short ones will do. Use buy instead of purchase, help instead of assist, about instead of approximately, and so on.

Plain language lists can help spot problem words and consider alternatives, but keep in mind that plain language is more than just a list of words to avoid—it’s a way of writing.

Words to avoid

  • agenda (unless you’re talking about a meeting)
  • advancing
  • collaborate (use working with)
  • combating (use working against or fighting)
  • commit or pledge (we need to be more specific — we’re either doing something or we’re not)
  • countering (use answering or responding)
  • deliver (pizzas, mail, and services are delivered — not abstract concepts like improvements or priorities)
  • deploy (unless you’re talking about the military or software)
  • dialogue (we speak to people)
  • disincentivize or incentivize
  • empower
  • execute (use run or do)
  • facilitate (instead, say something specific about how you are helping)
  • focusing
  • foster (unless it’s children)
  • illegals or illegal aliens (use undocumented immigrants)
  • impact or impactful
  • initiate (use start)
  • innovative (use words that describe the positive outcome of the innovation)
  • in order to (use to)
  • key (unless it unlocks something, use important or omit)
  • land (as a verb only use if you’re talking about aircraft)
  • leverage (unless you use it in the financial sense)
  • liaise (use collaborate, work with, or partner with)
  • modify (use change instead)
  • overarching
  • progress (what are you actually doing?)
  • promote (unless you’re talking about an ad campaign or some other marketing promotion)
  • robust
  • simple or simply (use straightforward, uncomplicated, or clear, or leave the descriptor out altogether)
  • slimming down (processes don’t diet)
  • streamline
  • strengthening (unless you’re referring to bridges or other structures)
  • tackling (unless you’re referring to football or another contact sport)
  • thought leader (refer to a person’s accomplishments)
  • touchpoint (mention specific system components)
  • transforming (what are you actually doing to change it?)
  • user testing (use user research or usability testing)
  • utilize (use use)

Present complicated information clearly so it’s easier to understand. If you need to include legal terms or technical language, include a short, plain-language summary or define your terms up front.

It’s fine to use technical terms when they’re appropriate for the audience or the situation, but you need to explain what they mean on the first reference.

If you’re publishing source code, see the 18F Open Source Style Guide for tips on making the project easy to use and understand.

Additional resources

Structure the content

Below you’ll find a few characteristics of online readers as well as our recommendations on ways to keep them in mind when writing and editing.

Important information first

Online, users tend to scan text until they find the information they need. No matter how carefully you craft your content, most people will only read 25 percent of it. This statistic isn’t meant to dishearten; rather, we believe it underscores the importance of getting content right.

Put the most important information in the first two paragraphs. That’s the section users are most likely to read. In journalism, this technique is called the “inverted pyramid.”

Break up text

Large chunks of text can overwhelm readers. Use subheads and bullet points; they provide clear narrative structure for readers in a hurry. Put information-carrying words at the beginning of the phrase, and use the active voice.

Instead of:

Looking into the regulation of campaign finances

Use:

Campaign finance law explained

If you’re wrangling a lot of data, tables can help you visualize that content. Long paragraphs cluttered with numbers or dates are more difficult to scan than, for example:

Report type Dates covered Due
Quarterly (Form 3, 3Z, 3L) January 1–March 31 April 15
April 1–June 30 July 15
July 1–September 30 October 15
October 1–December 31 January 31

Don’t use FAQs

Like our peers at GDS, we strongly discourage writing FAQs, or Frequently Asked Questions.

FAQs:

  • Are hard to read and search for
  • Duplicate other content on your site
  • Are usually not questions asked by the public
  • Mean that content is not where people expect to find it—it needs to be in context

If you’re thinking about posting FAQs, review the related content on your site and look for ways to improve it. Take the necessary steps to give users the best possible experience.

Ask yourself:

  • Is the content organized in a logical way?
  • Can you group similar topics together?
  • Is it easy to find the right answer?
  • Is it clear and up-to-date?

If people are asking similar questions, the existing content isn’t meeting their needs. Perhaps you need to rewrite it or combine several pieces of content. Pay attention to what users are asking for and find the best way to guide them through the process.

Keep refining

Content design is an ongoing process, and even published content isn’t really “done,” in a traditional sense — it’s not a static entity. To ensure that your content is helping users, you need to keep refining it over time.

When you’re creating content, it’s best to base your refinements on insights from users. This section addresses ways to test your content’s effectiveness and includes tips for archiving and deleting content without disrupting the user experience.

Testing and ongoing research

Set aside time regularly to make sure your content works for users. If you’re not sure where to start, check your web analytics to identify:

  • Pages with high or low traffic
  • Pages with high or low reading times
  • Common search terms
  • Common user flows within your site

You can also review:

  • User feedback from surveys, call center logs, and support emails
  • Recurring themes from channels like Twitter, Facebook, and tech blogs

You should make a habit of listening to users, too. Conduct usability testing sessions regularly to understand how people access, use, and interpret key pieces of content on your site. See Looking at the different ways to test content on the 18F Blog for more details.

Additional resources

Archiving and deleting content

You may occasionally need to archive or delete outdated content. Maybe it’s irrelevant after a recent policy change or redundant with other pages on your site. Avoid moving or deleting content without a good reason, because it can cause a lot of frustration for users. Changes to site structure may also slow down users who’ve learned specific navigation paths on your site.

As part of ongoing site maintenance, you should audit your content to keep everything updated and identify potential duplication. Depending on the size of your site, you may want to review everything on a yearly basis, for example, or look at one or two sections at a time.

Before you archive or delete anything, review your site analytics to understand how users are accessing the content now, and check in with the content owner or author to come up with a plan together. Be sure to consider cases that may not show up in analytics data too, such as:

  • Search engine results
  • User bookmarks
  • Links from external sites

Each of these can be addressed by ensuring you have redirects from the old URLs to the latest content.

When you’re looking at a particular page, think about the best way to meet user needs:

  • Who is this content for?
  • Is there a legal requirement for having it?
  • How often do people visit this page?
  • Are there any incoming links to it, either within your site or from popular referrers?
  • Are there other pages that cover this topic? Can you combine them? Which one shows up higher in search results?
  • Can you hide or archive the page instead of deleting it?
  • Was this content meant to expire quickly? Was the website the right channel for this type of content — or should posts like this move to a blog, newsletter, or social media account in the future?

If you genuinely need to delete something, give users a path to find what they need. This could include:

  • URL redirects
  • Ceding ownership of the content to another organization who can maintain it
  • Keeping content around and adding context that it is depreciated or no longer maintained
  • Making the content available elsewhere with an archiving service like the National Archives and Records Administration’s Government Web Harvests or the Internet Archive
  • Custom 404 pages to help users find what they’re looking for

Additional resources

Giving and receiving feedback

Giving and receiving feedback on writing is hard. Both need your time, energy, and care. That may feel daunting. But we all want our work to be strong and it only gets better with feedback.

The beauty of the writing process is that it’s iterative — everyone (yes, everyone) writes crappy first drafts. The important thing is to share the draft, gather feedback, revise, and repeat. Even published content isn’t really “done.” It’s important to keep refining, and incorporating feedback from your readers is part of that process.

Here are some ways to approach giving and receiving writing feedback.

How to give feedback

Start by reading the piece in its entirety before editing or making comments. Though you may be tempted to give line edits on an early draft, resist this temptation! It’s likely that much of the text will change from draft to draft, so your line-editing work may be lost by the final draft. Focus on the central goal or message of the piece—not specific wording or stylistic decisions. If you find yourself needing to comment on structural issues or key messages, it’s probably worth setting up a meeting to talk through things.

As you read, think about the answers to the following questions:

  • Is it clear?
  • Is it easy to follow?
  • Are there any gaps or places you get lost?
  • How might someone feel after reading this?
  • Does it leave you with any questions?
  • Are there any places that could use a story or concrete examples?
  • Does it assume knowledge that the reader might not have?

Respond as a reader and tell the writer:

  • What doesn’t feel right
  • What doesn’t make sense
  • What isn’t working — and what is!
  • What you want to know more or less about, and why
  • What questions you have
  • What doesn’t reflect your own experience

Ask questions to help the writer revise:

  • Who is the audience?
  • Why does this matter?
  • What does this mean?
  • How does this help the reader?
  • What’s the most important thing for people to understand?
  • What do we want readers to do next?

When people ask for feedback, they’re looking for your thoughts on what aspects of their work could be stronger. Even as you offer kindly worded suggestions for improvement, it’s nice to comment on what’s working in a piece, too. Everyone likes to receive recognition for what they’ve done well. Plus, you don’t want them to unknowingly change what’s working — sharing positive feedback can prevent them from doing so.

Everyone needs feedback, even professional writers. Don’t second-guess yourself as the reader. You don’t have to have the solution or right answer. Ask questions, let the writer know if something doesn’t make sense, and tell them what you like. Finally, thank them for asking for your feedback. It’s not easy, and it shows that they care about the work and their reader.

How to receive feedback

It’s natural to feel timid about sharing your work, especially if it’s an early draft. But sharing work early in the writing process has great benefits. Your colleagues can help you identify the strengths and weaknesses of your piece, which can help you narrow your focus and determine which sections need the most work. Likewise, your colleagues can point out interesting areas that you could expand on.

If you’re apprehensive about sharing your work, it can be helpful to label documents as drafts to help frame your readers’ expectations and perceptions. For example: ‘First draft: Giving feedback on writing.’ Sharing drafts with one person, rather than a larger group, can also help you ease into the process.

First, be clear about the type of feedback you’re looking for to ensure you get comments that are useful for the stage of writing you’re in. Here’s a summary of some types of feedback you can ask for and at what stage:

  • Collaborative: These are some initial rough ideas—feel free to dig in and change anything.
  • High-level edits: Observations about a piece’s general concept, structure, and intent — are most useful for early drafts. Are the big ideas coming through? Does the structure make sense? Is the flow logical?
  • Line edits: Better suited to later, more finalized drafts, whose ideas are fleshed out and which could benefit from some polish. How’s the voice and tone? Is the writing clear and consistent? What doesn’t make sense?
  • Copyediting: We’re about to publish this — are there typos or awkward phrases?

If your piece needs additional context, share it. There are all types of context that might be helpful: background information, strategies that have been tried in the past (and since abandoned), any legal considerations, audience needs or insights from research, or variations between our house style and a client’s content conventions.

If you have a deadline, be honest and realistic about it. And if you’re unsure about how long it will take your reader to give feedback, be honest about that, too — it’s OK to ask them whether your expectations align with their timeframe.

Lastly, show appreciation. Giving feedback takes time and energy. Thank the person for taking the time to read your piece and share their thoughtful observations. Consider sharing the end result with them so they can see how their feedback helped you.

Additional resources

Make content web-friendly

One of the simplest ways to present accessible, maintainable information online is to use HTML.

It can be tempting to choose file formats that are more convenient for the author, such as PDF or Word. However, presenting content in PDF, Word, or similar formats can make content much harder to use.

Therefore, we strongly recommend using HTML for all web content. Here are some of the benefits:

  • It’s much easier to link to specific pages or sections of HTML pages.
  • It’s much easier to update and maintain HTML content.
  • HTML content avoids breaking the user out of their browsing flow, and maintains the context of the site’s navigation and structure. Conversely, this often means that HTML pages are easier to re-find and less likely to be “orphaned” or left online beyond their usefulness.
  • All web content should be accessible, and this is much easier to accomplish and enforce with HTML content. It is possible to create accessible PDFs, but requires significant specialized training and effort for each document.
  • HTML content is generally more accessible to search engines, and even within a page, HTML content is often more searchable and scannable for users seeking specific information.
  • HTML content is much more responsive-friendly (especially on responsive websites), and some systems don’t display PDFs within the browser. This makes for a confusing user experience, and may cause some users to be unable to view or find the PDF at all.

Here are some alternate approaches for situations in which people often choose PDFs:

  • When the content includes images, tables, or other graphics that you aren’t sure how to display in existing page templates: Instead, work with a designer or your web publishing team to explore how you can translate the information you need into native web content.
  • Formal or policy documents that are infrequently or never updated: Instead of using PDF to convey permanence, use document structure, clear timestamps, and design cues to help users understand the context they need to interpret the document.
  • Manuals or other long documents: These are especially crucial to make available as HTML content, especially because they often need to be kept up-to-date as technology or processes change. If you expect users to need offline access, support PDF as an alternate format or ensure clean, useful print stylesheets so that users can generate their own PDF.

PDF-first may be the appropriate choice for content that’s primarily and only intended for print use. This might include brochures, business cards, or forms that must submitted as paper copies. (Though a better long-term approach is to change forms and processes so people can submit soft copies or complete the form online.)

If you do choose to present content in PDF, remember to ensure the information is also available on your website in an accessible, linkable, and responsive HTML format.

Avoid using formats for which users need specific, proprietary software (for instance, Microsoft Word, PowerPoint, Pages).

Abbreviations and acronyms

Abbreviations are any shortened or contracted word or phrase. For example, writing St. instead of Street, or Rx for prescription, or DC for District of Columbia.

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, courtesy of Dr. Rebecca Johnson: 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:

Forms issued by the Office of Government Ethics include the OGE-450 and the OGE-278.

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

Capitalization

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.

See additional capitalization rules in the Specific words and phrases section.

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

See also: information about optimizing headings.

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:

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

Names

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 Mississippi.
  • 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 and percentages

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.

Dates

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.

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.

Punctuation

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.

Commas

We use the serial comma (sometimes called the Oxford comma). In a list of three or more, include a comma before the conjunction. For example: Please buy apples, bananas, and naan chips.

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. For example, D.C. Tech Lady Hackathon + Training Day

Slashes

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

Specific words and phrases

Below are rules for how we use common words and phrases. The bold term shows the accepted form (capitalization, hyphenation, punctuation), with accompanying text explaining usage.

  • 18F employees, 18F team members, or 18F staffers. Avoid all iterations of 18F-r.
  • ages, avoid hyphens in ages unless it clarifies the text. For example, a group of 10 18-year-old White House tourists.
  • agile
  • a.m.
  • back end, back-end development
  • Congress refers to the U.S. Senate and House of Representatives.
  • congressional is lowercase unless part of a proper name. For example, Congressional Record
  • DC, not D.C.
  • DevOps
  • digital coalition
  • drop-down when used as an adjective. For example, drop-down menu. drop down when used as a noun. For example, an option from the drop down. Never dropdown.
  • email, not e-mail
  • executive branch
  • federal, unless part of a proper noun. For example, Federal Bureau of Investigation
  • federal government, not Federal Government or Federal government
  • fiscal year is lowercase. It’s okay to abbreviate as FY on the second reference.
  • front end, front-end developer
  • GitHub
  • government, unless part of a proper noun. For example, Government Printing Office
  • homepage
  • human-centered design, but we prefer user-centered design to describe 18F’s principles and work.
  • info is an acceptable shortening of information. In formal situations, use the full word.
  • internet
  • JavaScript
  • kanban
  • login when used as noun, for example, I forgot my login name and password, or when used as an adjective, for example Make sure the login page is 508 complaint. log in when used as a verb, for example, Log in to access your calendar.
  • open source, open source software
  • percent is preferred more than the % symbol. For example, 10 percent of respondents.
  • p.m.
  • README
  • Scrum should be used to refer to the set of practices for the agile method. We don’t use that term for the daily meetings and instead use daily standup.
  • single sign-on
  • sitemap
  • startup
  • tech is an acceptable shortening of technology. In formal situations, use the full word.
  • to do (noun) and to-do (adjective). For example, your to dos or your to-do list.
  • United States government or U.S. government, not U.S. Government
  • URLs should be lowercase, even when they appear at the start of a sentence. For example, notalone.gov launched today.
  • U.S., not US or USA
  • user-centered design, preferred term over human-centered design to describe 18F’s principles and work.
  • U.S. Web Design System on first use and Design System on subsequent references
  • Wi-Fi

Voice and tone

If you’re like many folks, you might not be sure of the difference between voice and tone. Maybe you’ve never deliberately crafted a voice and don’t know where to start. Not to fret! In this section, we’ll discuss the differences between voice and tone, how we describe our organizational voice, how to establish your own voice, and how to choose a tone that’s appropriate for whatever you’re writing.

The difference between voice and tone

It’s a common question and one that young writers find themselves asking often: What’s the difference between voice and tone?

Our voice is our unique personality. It can be helpful to think of voice as analogous to a person’s voice. Just as you can identify your best friend in a crowd as soon as you hear her distinctive laugh, you can use an author’s or organization’s voice to identify a piece of writing even if you haven’t seen the byline. A well-crafted voice communicates personality and values — it’s a distilled representation of an author or organization.

Tone is more like attitude — the emotional context of a piece. It can be helpful to think of authorial tone as analogous to a person’s tone of voice. Just as a person would use a somber, sympathetic tone of voice to console a friend about the loss of a pet, an author writing a story about a natural disaster would most likely use a somber, serious tone. Conversely, an author writing a blog post about the launch of a new product might use an enthusiastic, upbeat tone.

Our voice

At 18F, we like to communicate in a friendly, straightforward way. We consider our voice to be:

  • Authoritative
  • Conversational
  • Friendly
  • Instructive
  • Welcoming to all audiences

We believe that government communication can — and should — be fun and easy to read, and our voice represents this.

Here are a few sentences, taken from the 18F Content Guide, that exemplify our voice:

We created this guide for reference on an as-needed basis. It’s here when you’re wondering whether to capitalize the word federal, for instance, or when you’re wondering how to create a friendly, informational tone.

Use contractions

In all of the communication we produce, we want to create a strong connection with our users. We want to get them the information they need in a straightforward way and show that we know what’s important to them. As a government organization, we need to sound somewhat official; we also recognize that official doesn’t need to translate to stuffy, archaic, or aloof.

For this reason, we use contractions in the writing we create for our site. We also encourage clients to consider using contractions, too, though we recognize this may not be the right choice for all contexts.

The government is run by people for the benefit of people, and we never want users to forget that 18F is a group of enthusiastic, dedicated, hardworking (and friendly) folks. This desire informs how we craft our voice.

Establishing your own voice

Whether you realize it or not, you already have a unique voice; the tricky part can be classifying it and pinning it down.

To describe your voice — which, in turn, will allow you to diagram it, create guidelines around it, and make it reproducible — you’ll need to do some investigation and self reflection. Ask yourself these questions:

What are my core values? Your voice is a reflection of your core values. Before you craft a voice, consider the values your organization represents and how you can translate these into stylistic patterns. If you’re part of a young organization that hasn’t yet codified its values, you might use this opportunity to start that conversation. Crafting a voice before you’ve determined your organization’s values can be dangerous — your voice might not reflect what you eventually decide on. Along the same lines, if your organization is undergoing a large-scale values overhaul, you’ll want to make sure your organizational voice reflects your new values.

Who is my audience? In writing, as elsewhere, your audience is paramount — without them, you’d have no reason to write. Put yourself in their situation and think about the stylistic traits that might appeal to them. Remember, your voice doesn’t need to appeal to everyone (and, in fact, shouldn’t — cure-alls cure nothing, as the old saying goes).

Use your answers to these questions to craft a description of your voice. Once you’ve come up with your description, look it over and identify any contradictions or holes (never a good thing). While voices should be nuanced, they should also be cohesive.

Choosing a tone

As we mentioned earlier, your voice is a constant, but your tone is a variable. Consider the following: If you’re having an irredeemably terrible day, you might get peeved at a store associate who chirpily (and repeatedly) asks if they can help you with anything. Instead of picking up on your nonverbal — or perhaps verbal — cues, this associate is tone-deaf. The associate maintained a consistently helpful voice, but they failed to shift their tone from energetic to restrained. As a result, their message (however valuable or well-intended) is lost on you.

To avoid going the way of the associate, think about your users’ needs in different situations. Use these needs to determine your tone.

Let’s consider three examples that target three different reader groups. Obituaries, technical blog posts, and marketing emails targeted at newly engaged couples have vastly different tones. Why? The three types of writing correspond to audiences in three highly different emotional states.

Type of writing Intended readership Tone Example
Obituary of a prominent community member People who knew (or knew of) the deceased Respectful, reverent, somber “Professor Pelham was respected by his colleagues and revered by students, many of whom would wake before dawn on registration day to ensure gaining entry to his classes. His wit, gentle humor, and compassion left their mark on everyone he talked to.”
Blog post announcing open source documentation guide Developers and other readers with a strong tech background Direct, impartial “The Open Source Style Guide is a comprehensive handbook for writing clear, accessible, and user-friendly documentation so that your open source code repositories are accessible both internally and externally.
Marketing email from the boutique bridal department of a well-known clothing company Newly engaged women (ages 28 through 33) Enthusiastic, earnest, bubbly “Say ‘I do!’ to 25% off. Now through July 3rd, take an additional 25% off all bridal wear and accessories. Celebrate your big day in style (and get a jumpstart on your honeymoon fund!).”

If you’re having trouble finding an appropriate tone, try reframing the situation: How would you talk to a friend who’s in the same situation as your target user? Remembering that written communication is a conversation can help you settle on the best tone for your purpose.

Further reading

  • MailChimp’s voice and tone guide: This beautifully designed tool allows you to select different content types and learn more about what the user might be feeling while reading them, along with examples of tones appropriate to those content types. Super simple to use, this is a great quick reference for creating diverse types of content.
  • The nonviolent communication (NVC) framework for feelings: Pinpointing the most appropriate tone for a piece of content starts with identifying what your readers might be feeling when they read that content. This list of feelings is broken into two categories — feelings you experience when your needs are being met and when they aren’t.
  • Jeff Goins’ voice activities: Use author Jeff Goins’ ten-step exercise to pinpoint your authorial voice. The “steps” are actually discrete activities and can be undertaken in any order.
  • If you’re still a little confused about voice and tone, Wheaton College provides an excellent breakdown of those — and more — writing components.
  • Fast Company has also weighed in on the voice and tone discussion.

Forms

Many of our projects involve forms — editing existing forms and creating new ones. We’ve compiled the following list of strategies to help you create forms people will find easy (and maybe even enjoyable) to complete.

Use an appropriate tone

Understanding how people might be feeling as they encounter your form can help you make more informed decisions about the right tone to use. Is your form associated with a high-stress experience or a more benign one? Are you requesting deeply personal, or more general, information? How might this impact people’s frame of mind?

Consider the purpose and situational context of the form you’re designing, along with the type of information you’re collecting. For example, if you’re preparing a form someone will use to secure medical services for a family member, you might use a reassuring, direct tone. If you’re designing a form folks can use to register for a professional conference, you might use a livelier, more jovial tone.

Start with easier questions

In addition to tone, the sequence of your form’s questions can influence the user experience it creates. Start your form with easier-to-answer questions — basic demographic information, for instance — and then work up to more comprehensive or difficult-to-answer ones. Starting with easier questions helps people ease into the experience of completing your form.

Provide enough context

Understanding people’s possible attitudes toward the requests you’re making can help you determine where to provide contextual information and how much to provide. If you’ll be requesting Social Security numbers, financial data, or personal medical information, you may want to share why you need this information and explain the safeguards you’ll be taking to protect it. Providing this context can help users feel more at ease and create a more satisfying interaction.

Design with devices in mind

We strive to design content that’s equally accessible — and enjoyable — across all devices. That said, keeping your users’ device preferences in mind can help you make decisions about form language. If you know most people will be accessing your form on mobile, consider creating shorter field labels. If most people will be accessing your form in the browser, you can create longer, more descriptive field labels without compromising the user experience.

Keep it concise

Brevity is especially pertinent when creating forms. People are completing your form to achieve a certain end; don’t create more work for them by using unwieldy or long-winded descriptions.

Create labels that are concise and to the point — “First name” is much easier to comprehend at a glance than “What moniker do you go by?” Short labels are also easier to read on mobile, and potentially save you money on translations.

Align field length with response length

Fields should be the right size for the information you’re requesting. Fields for capturing a first or a last name or a city of residence can be short; fields meant to capture longer responses — a complaint or request, for instance — should be sized so that people can see what they’re typing before submitting it.

Don’t use placeholder text as labels

Labels should appear above fields, not as placeholder text inside those fields. Using placeholder text as labels can create confusion around which information belongs where (it’s easy to forget what a field is for if it’s not labeled), and it can make form completion more difficult for people with disabilities.

Don’t make optional information required

If a piece of information is optional, tell the user. Requiring only the information that’s truly required will save your users time — something all of us can appreciate. It’s also a best practice to label only optional fields or only required fields, depending on which option is less overwhelming. For example, if your form has four required fields and one optional field, it would make more sense for you to label the optional field.

Follow accessibility best practices

If not designed thoughtfully, forms can present major accessibility issues. Inaccessible forms can impact a range of people — screen reader users, keyboard-only users, people with cognitive disabilities, and those who are mobility impaired, to name a few — creating unnecessary barriers. For more detailed information about how to make forms accessible, see our accessibility guide.

Additional resources

Headings and titles

Most people start their search for information with a search engine. If they can’t find your page, they won’t be reading your content.

To help users find your content, you have to use their vocabulary and keywords, starting with your page title, summary, and first paragraph.

Find the right keywords

Use search tools like Google Trends to compare different versions of headings to see which will be more effective. What you’re calling the subject of your page might not be what your users are calling it. With Google Trends, you can input two or more different words or phrases and see over time how often people have searched for them. Generally, it’s best to use whichever phrase is used more often in your heading.

For example, the phrase extractive industries is part of the name of the U.S. EITI site, but extractive industries isn’t a familiar term for many users (and there aren’t very many searches for that term). To help make content more findable, the site includes familiar terms like natural resources, fossil fuels, and renewable energy whenever possible.

A Google Trend search shows that natural resources and fossil fuels are both more popular search terms. The page about natural resource production in the U.S. is a great example of how those terms can be included in headers.

Optimize the content

Once you know the most popular keywords, you can incorporate them judiciously in:

  • Titles
  • Headings
  • Introductions and summaries
  • Chapter and section titles
  • Metadata descriptions

See also: information about heading capitalization.

Images

Images are an excellent way to communicate information.

Use relevant photos, graphics, and other visual elements when they clarify what you are communicating. The same principles we apply to written content apply to images:

  • Address the user: Focus on illustrating or drawing attention to specific points you want them to understand.
  • Be concise: Don’t use numerous or complex images when one or two simple ones will do.
  • Be conscious: Consider how your image choices include or exclude.

Common uses of imagery at 18F

  • Group pictures or images of people working together are great additions to posts about meetups, hackathons, or other events.
  • Screenshots can go a long way in explaining design and user experience techniques in how-to pieces.
  • Consider GIFs to illustrate functionality, show users a series of steps, or give examples of interactive content in a static post.

An image on the 18F blog that spans the full width of a blog post should be 1600 pixels wide, though it will only display as 800 pixels wide. If possible, use vector images in the SVG format. Full-width images that precede body copy should illustrate the theme of the full post, not just one small part. Avoid using screenshots of text above the body copy as they can be confused with the body of the post. If you’d like to use a screenshot of text, consider slightly tilting the image to the left—say, 6 degrees or so—so it is clearly separate from the body of the page. If a post includes an image that illustrates only a specific section, put that image directly before that section. When choosing images, make sure they are not so tall as to push other content off the screen. Captions for images should be directly below the image and italicized.

When floating images left or right around the text of a post, make sure the images are between 500 pixels and 100 pixels wide, but when using multiple images on the page, consider how those images might look as the text wraps on smaller screens. Make sure you test your content on a phone to ensure the images don’t impede the readability of the text.

Copyrighted images

Government works, including both written content and images created by 18F staff, are in the public domain by default.

If you want to use existing images, check out the 18F Visual Identity Guide or explore public domain options before resorting to works under copyright. The process of publishing will be simpler, and questions of attribution will be much less confusing for the public if they choose to use our written content elsewhere. Look for images with a CC0 license.

Good places to search for public domain (CC0) images:

If you do use copyrighted images:

  • Try to find use one with few restrictions on reuse like a Creative Commons Attribution license.
  • Get permission from the copyright holder.
  • Attribute the photo to the source (especially if required or requested).
  • Where possible, link to the source online.

Accessibility

Images must comply with 508 standards and accessibility guidelines. The broad requirement is that any information presented in an image must also be presented in an alternative format (for people who cannot view images). While 508 compliant is the minimum threshold for our content, we generally hold our work to a higher standard specified by the Web Content Accessibility Guidelines’ (WCAG) AA standard.

For images this means every image on a web page must have alt text describing the image. Additionally, any text that appears in the image must also appear in the alt text. Most screen readers already add “Image of” when reading out an image, so alt text like “Image of the 18F logo” is redundant because screen readers will read it “Image of image of the 18F logo.” A good rule of thumb is to limit alt text to 150 words, anything longer should be placed in the content of the page.

Images that serve solely to illustrate or provide visual interest for other nearby content do not require alt text, but they do require the alt attribute to be present (in code, this is done with alt=""). Otherwise, screen readers will fall back to uttering the URL of the image.

Note also that if the image is associated with an action or concept, the alt text should refer to the name of the action or concept rather than the literal description of the image. For example, if a search field has an image of a magnifying glass to signify that clicking on it will initiate a search, “Search” will be more useful alt text than “Magnifying glass”.

For more details and examples, read the 18F Accessibility Guide.

Captions

When captioning an image, the goal is to add additional context and information. Don’t simply state what the reader is able to see by looking at the photo itself. Captions should increase depth and understanding. They are also a good place to include attribution information when images are under a Creative Commons license or other groups have granted 18F permission to use an image.

Style guides

We often develop project-specific style guides to support our partners and their audiences. We usually call these documents content guides, because most of our partners already follow a style guide like AP, GPO, or Chicago.

Guidelines

Here are a few things to keep in mind when you’re developing style guides:

Respect the partner’s existing style. Assume that your partner has an agency-level style guide and ask about it.

  • If they don’t have a style guide, start with AP since we’re most familiar with it and many of our partners use it.
  • If any of the existing style guidelines inhibit clarity or usability, talk with the partner about it, backing up your recommendations with insights from user research.

Keep it brief. Don’t try to document every possible grammatical or style issue. Keep your guide short and sweet so it’s easy for people to reference. Most of our guides include:

  • High-level notes about voice and tone
  • Usage guidelines
    • Acronyms and abbreviations
    • Capitalization
    • Numbers
    • Punctuation
    • Web styling, such as headers or glossary terms
  • Specific words and phrases

Focus on what’s new or particularly unique. If you’re using sentence case or avoiding acronyms, for example, call that out and include inline examples. If you need to use specific terms or technical jargon with users, include suggested phrasing to help other writers follow along.

Share and refine it. Post the guide on a wiki or in a pattern library with other project documentation — don’t bury it in a PDF. Make it easy for people to find and update the guidelines as questions come up.

Examples

Technical and interface writing

At 18F, we often write technical documentation, guides, forms, and interface messages. In most of these cases, it’s safe to say the reader is learning something new or troubleshooting. These guidelines will help you write clear, concise instructions, which will provide your reader with the best possible experience.

Basics

Do the hard work to make it simple.

Help the reader follow along. Break instructions or processes down into individual steps. Use short, simple sentences with words people use in everyday conversation.

Refer to navigation labels, buttons, and menus as they appear in the app or website. Verify the spelling and capitalization as you write. Be specific.

Instead of:

Open a new meeting invitation.

Use:

In Google Calendar, click Create.

Direct the reader.

Start your sentences with active verbs or clear objectives.

Instead of:

Help us understand what kind of help you need by creating an issue in GitHub.

Use:

Create an issue with details about your request.

Or:

To get started, create an issue in GitHub with details about your request.

Focus on what the reader can do rather than what they can’t. (This is known as using positive language.)

Instead of:

You cannot continue without signing in.

Use:

Sign in to continue.

Guidelines

Titles and headings

Be consistent with how you phrase titles. If your guide or tutorial has several pages, stick to the same naming convention for scannability, such as:

  • Nouns: Policies, Teams, Offices
  • Verbs: Create an account, File a report, Download our data

Use sentence case for headings. (If you’re writing articles for the 18F Handbook or 18F Pages, the table of contents will auto-generate based on your <h2>, <h3>, and <h4> tags or Markdown headings.)

Introduction

Include a short two- or three-sentence summary about the document to help the reader confirm whether they’re in the right place, and improve search engine indexing.

Code

Use backticks to style text and code snippets readers may want to copy and paste. For example:

Use the legend element to offer a label within each form element.

Copy and paste mkdir /home/foo/doc/bar && cd $_ into Terminal.

In the first example, legend is an HTML element and should be styled as code. “Element” is a technical concept and shouldn’t be marked up as code. “Label” is both a concept and an HTML element but is used here in the former sense and should not be styled as code.

Do not capitalize code elements, even at the start of a sentence, unless the term is capitalized in the code itself.

Use fenced code blocks for multi-line code snippets, and specify the language to enable syntax highlighting on GitHub:

In JavaScript, to get the current value of a select element with an id of mySelect, use this:

var el = document.getElementById("mySelect");
var value = el.options[el.selectedIndex].value;

Use straight quotes within code blocks rather than curly (or smart) quotes.

Code-like elements

The same rules apply to pieces of text that must be used exactly as presented, such as passwords or Wi-Fi network names:

someCl3v3rN4me is the name of our Wi-Fi network.
Your password is PleaseChangeMeSoon.

Interface elements

Use clear verbs to tell readers how to interact with interface elements:

  • Choose from drop-down menus.
  • Select or deselect checkboxes and radio buttons.
  • Click or tap buttons.
  • Follow or open links.

In the 18F Handbook, we emphasize the name of the interface label like so:

  1. In the File menu, choose Save.
  2. Select I agree.
  3. Click Continue.

Tables

Tables are generally suitable only for data: two or more “objects” (rows) that share two or more “values” (columns). In tables, column widths are the same for all rows, which can make them easier to scan visually. Tables are easily navigable for sightless users so long as the content is organized in a logical way. Here are some other guidelines to consider:

  • When listing numbers, it’s good practice to align them to the right of their cell, with the same decimal precision (“40.50” and “1.00”) so that the numbers are easier to compare while scanning.
  • Always align column headings up with the values in the columns. For example, numeric column headings should be aligned right if the values are, too.

It’s rare that a document lives on its own. Tell people where to go for help if they have questions.

For documentation and guides, you might say:

For more information, see the 18F Code of Conduct.

To refer the reader to a Slack channel, follow this format from the 18F Handbook:

Still have questions? Ask in #newcomers.

If your work relates to several other documents, pick the most important ones or gather the links in a section at the bottom.

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. Do link to useful resources, like slide decks or how-to guides, from private individuals or companies. If you mention a trademark, capitalize and punctuate it in the trademark holder’s preferred style.

URLs and filenames

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.

Domains

Domains should reflect the user’s needs and not those of the organization. If your department is several layers deep in terms of bureaucratic structure, it’s unlikely that this is important to users, and there is likely minimal cost associated with using a more shallow domain.

It’s not necessary to have www. at the start of a domain. This is a holdover from the early internet. Any domain that has a www level should also work if that level is omitted.

Domains should not be more than three levels deep in most cases: 18f.gsa.gov is fine, but content-guide.guides.18f.gsa.gov would not be. It’s rare that more than four levels is justifiable.

At the same time, it’s not necessary to have a two-level domain for everything.

Domain names should be short, using abbreviations unless those are likely to be meaningless to users.

If a domain level has more than one word, you should strongly consider separating the words with dashes to make sure users read them the way you intend. If 18F had a project called EARS that for some reason needed a two-level domain, that domain should be 18f-ears.gov and not 18fears.gov (ears.18f.gov would probably be the ideal).

Domains are case-insensitive. They should be written as lowercase.

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: /content-guide/urls-and-filenames/ reflects that urls-and-filenames is part of content-guide. If this were a much larger guide, it’s possible that it could be divided further, for example /content-guide/urls-and-filenames/creating-urls/.

Each level of a path should make it possible to find the content beneath it:

  • The content at the root level should reflect that /content-guide/ is present.
  • /content-guide/ should make it easy to find urls-and-filenames/.

Conversely, the user should be able to remove a level from the path and end up at the parent of the original content.

Paths should be designed to be sensible for the user, not to reflect internal technical or bureaucratic structure. For example, filename extensions like .php should be avoided as they reflect the internal technology used on the server (and will not reflect even that if the site later changes to a different technology).

When separating words in a path, use hyphens. Hyphens are commonly understood by search engines to indicate word breaks (whereas other separators, like underscores, are not).

Paths are case-sensitive. They should be lowercase, regardless of what they contain, as uppercase letters make them more difficult to type (and to remember).

Examples

Domain names

  • Starting point: www.longnamecreationservice.departmentoflongnames.bureauofnames.gov.
  • Slight improvement: longnamecreationservice.departmentoflongnames.bureauofnames.gov.

    Rationale: www is unnecessary and omitting it makes the URL easier to type.

  • Very slight improvement: long-name-creation-service.departmentoflongnames.bureauofnames.gov.

    Rationale: Hyphens make the URL easier to read. The same would be true for the other levels of the domain, but we’re assuming you don’t have control over those in these examples.

  • Improvement: long-name-creation-service.bureauofnames.gov.

    Rationale: The user doesn’t need the URL to reflect that the service belongs to the Department of Long Names.

  • Better: lncs.bureauofnames.gov.

    Rationale: This is shorter and easier to type. However, it relies on users thinking of the service by that abbreviation.

  • Better: make-long-names.bureauofnames.gov.

    Rationale: If the users aren’t familiar with that abbreviation, a shorter description of what the service does is better to have as the lowest level of the domain.

Paths

  • Starting point: /services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php?action=create.
  • Slight improvement: /services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php.

    Rationale: Assuming that creation is the most likely action users will want to take, make it the default and strip the requirement for the query string.

  • Slight improvement: /services/default/php/forms/departmentoflongnames/longnamecreationservice/.

    Rationale: The default page should be delivered automatically, making the inclusion of index.php unnecessary. Also, hide the technical details (.php).

  • Improvement: /departmentoflongnames/longnamecreationservice/.

    Rationale: Users don’t need to know the technical setup of the site.

  • Improvement: /department-of-long-names/long-name-creation-service/.

    Rationale: Words should be separated with hyphens.

  • Better: /department-of-long-names/lncs/.

    Rationale: As above, if the users are familiar with the abbreviation, use it to make the path shorter.

  • Better: /department-of-long-names/make-long-names/.

    Rationale: As above, if they aren’t familiar with the abbreviation, use a shorter description of what the server does.

Both

  • Starting point: www.longnamecreationservice.departmentoflongnames.bureauofnames.gov/services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php?action=create.
  • Improvement: make-long-names.bureauofnames.gov/department-of-long-names/make-long-names/.

    Rationale: This combines the suggestions from the previous two sections.

  • Better: make-long-names.bureauofnames.gov.

    Rationale: This is reasonable if the Department of Long Names has only a couple of services that might be popular enough to warrant their own subdomains, particularly if they don’t necessarily fit cleanly into other content and stand alone.

  • Better: bureauofnames.gov/department-of-long-names/make-long-names/.

    Rationale: This is reasonable if the Long Name Creation Service is one of many related services that the Department of Long Names provides.

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. It’s most difficult to accomplish when moving from URLs that include query parameters, as some early website systems did. Sensibly-constructed URLs are easier to migrate.

Some examples:

Changing subdomains

If we changed our name from 18F to 19G, we would change our domain, so this page would be located at https://pages.19g.gov/content-guide/urls-and-filenames/. We would keep the 18f.gov domain running, but all it would do would redirect everything to 19g.gov. Users who entered the old URL would be redirected and might not even notice the URL change.

If we decide to eliminate the pages subdomain and put this directly on 18f.gov, we would do essentially the same thing, keeping this subdomain and adding a rule to redirect to the same path on 18f.gov.

Changing paths

If we produce lots and lots of content in the future, it might become sensible to change our path to reflect this, and we might want to have a guides level, so that the new URL for this page would be: https://pages.18f.gov/guides/content-guide/urls-and-filenames/. In this case, we would add a rule that redirects everything starting with /content-guide/ to /guides/content-guide/.

This also means that URLs, and parts of URLs, should not be re-used. Once we use /content-guide/ to refer to this guide, we can no longer decide in future to use /content-guide/ as the location for something else, even if we later change the URL for this guide.

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.

Examples

Capitalization on a web page:

gsa.gov is the General Services Administration site.

Capitalization in print:

gsa.gov is the General Services Administration site.

Delimiting an awkward URL in email:

When you get the chance, could you redirect <example.com/spaces in URLs are bad/> to <example.com/spaces-in-urls-are-bad/>, as per our guidelines, and make the latter the definitive URL for the page?

URL Structure

  1. The protocol. For example https://, http://, or ftp://. The :// is always present.
  2. The domain. For example 18f.gsa.gov. This is “where on the internet” the URL is referring to. Also called:
    • site
    • domain name
    • server
  3. Optional: the port. A number specifying how to access the content on this particular domain. Not normally used on production sites. Follows the domain, separated by a colon, for example http://dev.example.com:8080.
  4. The path: what resource on the domain the URL is referring to. If omitted, defaults to /, the “root level” of the domain. Always starts with a slash, and different levels of resources are separated by slashes. For example: /content-guide/ is the path in https://pages.18f.gov/content-guide/.
  5. Optional: the query string. Normally contains parameters that have been submitted to the site, for example with searches. ?q=18f+content+guide is the query string in https://www.google.com/search?q=18f+content+guide.
  6. Optional: the fragment. Normally this indicates a specific section of a page, but can also be used for other things by web applications. #main is the fragment in https://pages.18f.gov/content-guide/specific-words-and-phrases/#main.

The protocol should almost always be https:// unless you’re forced to use http://. Users entering http:// as the protocol should be redirected to https://. If at all possible, your URL should not contain a port. Query strings should also be avoided. Fragments can be used as a helper for the user, but should not be necessary for the user to find the relevant content.

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 18F Code of Conduct.

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

Screen reader-only text

In some situations, descriptive links may be overly verbose or redundant for sighted users. Here’s an example from the betaFEC site:

betaFEC screenshot

Here the Learn more link is appropriate for sighted users, but it may be confusing to screen reader users. In such situations, it’s possible to add invisible text just for screen reader users. For example, the U.S. Web Design Standards has a special CSS class called usa-sr-only for this purpose. Using this class, the aforementioned Learn more link might be written in HTML like so:

<a href=”essentials-house-and-senate-candidates-and-committees/”>
  Learn more
  <span class=”usa-sr-only”>
    about candidate and candidate committees
  </span>
</a>

This would keep the link concise for sighted users, while also providing important context for screen reader users.

If you want to use text intended only for screen readers on your project but are unfamiliar with CSS, ask your project’s front end developer for help. They can create a CSS class for you if one doesn’t already exist. Alternatively, reach out to #g-accessibility or #g-frontend in Slack!

Additional resources