Data.gov Style Guide

(Draft)

Writing for Data.gov

Data.gov is the federal government’s open data portal, providing access to datasets from nearly 100 federal agencies. Many non-federal sources, such as state and local government data, are also discoverable on Data.gov. Data.gov features highlights and updates on recent federal government data releases and events. There are several Data.gov Topics on issues such as education, climate, and public safety where users can find curated datasets and content. As there are many agencies contributing content to Data.gov, this style guide is intended to help us make all Data.gov information readable and understandable. This style guide borrows from the UK’s Style Guide and will be updated as Data.gov evolves. We welcome suggestions and feedback!

Active voice

Use the active rather than passive voice. This will help us write concise, clear content.

Addressing the user

Address the user as “you” where possible. Content on the site often makes a direct appeal to people to get involved or take action, e.g., “You can submit an idea for this data challenge.”

Avoid duplication

What are you and other contributors publishing? Are users across the world seeing a coherent view? Check that the user need has not already been covered. That doesn’t mean check the information you have – it means check the user need. Duplicate content confuses the user and damages the credibility of Data.gov. Users give up or go to another data source because they aren’t sure they have all the information.

If there are two pieces of information on a subject, how will the user know if there are three and the user has missed one? We also fight with ourselves for search results if we duplicate information. If something is written once and links to relevant information easily, people are more likely to trust the content.

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 remain human (not a faceless machine)
  • emotionless – adjectives can be subjective and make the text sound more emotive and like spin

You should:

  • use contractions (such as “can’t”)
  • not let caveats dictate unwieldy grammar – say “You can” rather than “You may be able to”
  • use the language people are using – use Google Insights to check for terms people search for
  • not use long sentences with complicated sub-clauses
  • (Note: words ending in –ion and –ment tend to make sentences longer and more complicated than they need to be.)

Capitalization

You should capitalize

  • President, Presidential, and Presidency (when referring to the President of the United States)
  • Federal
  • Nation (when it refers to the United States as in “Our Nation” or “This Nation”)
  • State (when it refers to a State as a single unit of government or when referring to the body of the United States, but not when it refers broadly to any one of the states in the United States)
    • The Attorney General of the State of Texas will attend the event.
    • The State officials warned against smoking.
    • This is now available in all 50 States.
    • Your local or state organization may provide assistance.
    • They traveled through seven states.
  • Government (when referring to the United States Federal Government)
  • Department and Agency (in further direct references to the entity, e.g., The Department or The Agency)
  • Administration (when referring to the Federal Government serving under the current President). Past administrations are not capitalized unless referred to by specific name, for example, The Reagan Administration.

You shouldn’t capitalize

  • local, government, department, and agency (except in titles like Department of the Treasury, Federal Government, and United States Government)

Gender-neutral text

Make sure text is gender neutral wherever possible. Use terms like them, their, and they.

Numbers

Spell out all numbers less than 10 and ordinals less than 10 (fifth, 29th, or 102nd). Use numerals for

  • sentences where two or more numbers appear in a sentence and one of them is 10 or more, figures are used for each number
  • numbers 10 and above
  • distance
  • percentage
  • money
  • age

Plain English

The list isn’t exhaustive. It’s intended to show the kind of language that confuses.

Data.gov is for everyone. 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 “like” instead of “such as.”

We also lose trust from our users if we write government ‘buzzwords’ and jargon. Often, these words are too general and vague and can lead to misinterpretation or empty, meaningless text. We can do without these words:

  • agenda (unless it’s for a meeting)
  • advancing
  • combating
  • commit/pledge (we need to be more specific – we’re either doing something or we’re not)
  • countering
  • deliver (pizzas, mail, and services are delivered – not abstract concepts like “improvements” or “priorities”)
  • deploy (unless it’s military or software)
  • dialogue (we speak to people)
  • facilitate (instead, say something specific about how you are helping)
  • focusing
  • foster (unless it’s children)
  • impact (as a verb)
  • initiate
  • key (unless it unlocks something. A subject/thing isn’t “key” – it’s probably “important”)
  • land (as a verb, only use if you are talking about aircraft)
  • leverage (unless in the financial sense)
  • overarching
  • progress (as a verb – what are you actually doing?)
  • promote (unless you are talking about an ad campaign or some other marketing promotion)
  • robust
  • streamline
  • strengthening (unless it’s strengthening bridges or other structures)
  • tackling (unless it’s rugby, football or some other sport)
  • transforming (what are you actually doing to change it?)
  • utilize

Always avoid metaphors. For example:

  • drive (you can only drive vehicles; not ideas or people)
  • going forward (unlikely we are giving travel directions)
  • in order to (superfluous – don’t use it)
  • one-stop shop (we are government, not a retail outlet)

With all of these words you can generally get rid of them by breaking the term into what you’re actually doing. Be open and specific.

Write conversationally – picture your audience and write as if you were talking to them one-to-one but with the authority of someone who can actively help. All audiences should understand our content. This isn’t “dumbing down;” this is opening up government information to all.

Publishing legal and technical content

Legal content can still be written in plain English. It’s important that users understand content and that we present complicated information simply. Where evidence shows there’s a clear user need for including a legal term, always explain it in plain English. Where you need to use technical terms, you can. They’re not jargon. You just need to explain what they mean the first time you use them.

Websites

Websites shouldn’t include “http://” at the beginning or “/” at the end.

Data.gov should be capitalized accordingly.

Help improve this content

Content suggestions are welcome, although we can’t guarantee your changes will be included. To suggest inline edits, simply log in to GitHub, and click the pencil icon of this file, or to comment, open a New Issue here.