Content guide

Welcome to our minimum viable content guide. This guide helps us use a consistent writing style and voice. It also documents some best practices of user-centered writing for us to refer back to, even as we iterate quickly.

Make your content user-centered

Use plain language

Plain language is humane. It’s accessible to everyone, including readers with cognitive disabilities and low literacy.

Simplify and clarify content

  • When you have a choice, choose the simpler word.
  • For example, choose use instead of utilize.
  • Avoid or explain jargon.
  • Spell out acronyms on first reference. Put the acronym in parentheses if you refer to it later.
  • Where you can, avoid negative phrases. Find a positive one instead because they're easier to understand.
    • For example, instead of “don’t have,” write “lack.”
  • Simplify and clarify your content, but not at the expense of clarity. Test your content with users to check if your content is easy to understand.
  • Add helper or explainer text where more context is needed.
  • For example, if a user types a city outside of California, helper text would kindly guide them to the appropriate next step: “Sorry, we don’t recognize that city. Please enter a city or zip code in California.”

Write clear sentences

  • Use active voice and strong verbs.
  • Make sure you don’t have hidden verbs.
  • Write in the present tense.
  • Turn gerunds into verbs where it makes sense (for example, instead of “helping,” write “help”).

Check your readability

Check your readability with an editor such as Hemingway App. The Web Content Accessibility Guidelines (WCAG) recommend a readability level of grade nine or below. But a readability editor won’t tell you whether users understand your content. So test your content with users.

Be concise

Aim for one thought per sentence. But try to vary the lengths of your sentences to sound more human and give your writing a smooth flow.

Write short paragraphs. But again, add a variety of paragraph lengths to keep readers interested.

Break up your content with headings to make the page easier to scan and summarize.

Break up content

  • Use bullet points, alerts, or information boxes where appropriate.
  • Emphasize the information that people most need. Consider using a larger font or bolding the words people are searching for. An alert would help users find a deadline, for example.
  • Choose the format that best matches your content.

Keep it conversational

Write how you speak. Imagine each period as a breath and each comma as a pause. Then read your writing out loud.

Use contractions. (For example: You’ll, we’ll, can’t, shouldn’t.)

Where it makes sense, start sentences with “And” or “But” to show the relationship between content and add a smooth transition.

Refer to the users as “you,” and the government or agency as “we.” Avoid “me” or “my” because it’s unclear if “me” refers to the readers or the writer.

Get to know your audience

Use Google Analytics and Search Console to learn the keywords people use to find your page. This shows you the language people are really using online. It can also show you users’ priorities and what they’re trying to find on your page.

Put users first

  • Share what your users need, not what you want them to think about you or your agency. Put their needs ahead of your agenda.
  • Give users the information they want and reflect their priorities.
  • Put the content they most want first on the page.
  • Highlight information they’re looking for.

Test your content with users

  • Give users a task to check if they can quickly complete it using your webpage.
    • For example, “Find the minimum wage in your city.”
    • Compare your prototype to the original page or current state and time users on the task.
  • Ask users:
    • Was the page easy to understand?
    • What questions do you still have?
    • Highlight any words or phrases that are difficult to understand.

Voice

This But not that
Welcoming to everyone Overbearing
Friendly Fake
Official Cold or distant
Conversational Disrespectful
Straightforward Blunt
Sensitive toward others Pretending to save people or know everything about them

Copyediting

We use AP Style with a few differences:

  • We use the serial comma (also called the Oxford comma) to avoid confusion.
    • Example: We brought apples, bananas, and oranges.

Headings

  • Use sentence case.
    • The first word is capitalized, as well as proper nouns.
    • Sentence case is friendlier.
    • It allows readers to recognize proper nouns more easily.
    • It’s how our brains are used to reading content, so we do it faster, according to Content Design by Sarah Richards.
  • For HTML heading tags, go in order and never skip a step.
    • Use only one h1 tag.
    • For example, h1, h2, h2, h3, h4, h2.
    • You can repeat a tag, but shouldn’t hop from h1 to h3, for example.
  • Put your headings in a Google Doc.
    • Select “View” > “Show Document Outline” to see the document structure.
    • Make sure your headings make sense in order and accurately summarize the page.

Titles

  • The title (different from the heading) appears when you hover over your tab. It helps users change between tabs on their browser.
  • Start with the page heading and then include the name of the site. That way, users have a complete understanding of what the tab is about.
    • For example: Content guide - Alpha.CA.gov

URLs

  • Include the h1 of the page to help search engines find your page.
  • Delete the conjunctions, prepositions, and articles — as long as the URL still keeps the same meaning.
    • A page titled “Hire a licensed contractor for home improvements” would become “/hire-licensed-contractor-home-improvements”.
    • But “growing-up-with-diabetes” should not be changed to “growing-diabetes” because it has a totally different meaning.
  • Put a hyphen between each word in a page title. That makes them readable as separate words by search engines.
  • Wherever a URL is spelled out, it should be linked.

Buttons and calls to action (CTAs)

  • Start with an active verb such as “Apply,” “Submit,” “Search.”
  • Avoid “See more” or “View more.” They assume everyone can see.
  • Keep it short but descriptive and distinctive.
    • An entire page of “Learn more” buttons wouldn’t help you make a choice, for example.
    • The user should have a good idea of where the button will take them.

Checkboxes

  • From Nielsen Norman: “Checkboxes are used when there are lists of options and the user may select any number of choices, including zero, one, or several. In other words, each checkbox is independent of all other checkboxes in the list, so checking one box doesn't uncheck the others.”
  • Use checkboxes where the items have an “and” relationship.
    • Anything with an “or” relationship should have bullet points or radio buttons. (For example: “You must be one of the following: a, b, c...”)

Bullet points

  • Use bullet points for a list of items that have an “and” or “or” relationship.
  • Capitalize the first word of every bullet point.
  • Only put a period at the end of a bullet point if it’s a full sentence on its own. But if each bullet point is a phrase or one word, you don't have to include a period. For example:
    • You must bring:
      • Bananas
      • Apples
      • Oranges

Form fields

Form fields allow users to enter in their information and get an answer specific to them and their needs.

  • Avoid placeholder text. From Nielsen Norman Group: “Placeholder text within a form field makes it difficult for people to remember what information belongs in a field, and to check for and fix errors. It also poses additional burdens for users with visual and cognitive impairments.”
  • Add helper text that appears outside of the form field if someone gives an invalid entry.
    • For example: “Please enter a nine-digit phone number such as 555-555-5555.”
  • Include a button to make it clear what type of results users will get, such as “Search for your city.”
  • Display valid options as a user starts typing to confirm what they can choose.

Step by step

The step by step content type walks users through multiple tasks that add up to one major task, such as “Hire a licensed contractor.”

  • Step by steps are especially helpful if the steps happen across different agencies.
  • Give a high-level summary in each step headline, and put smaller details in the “Show/Hide” text.
  • Each step should start with a verb.
  • Avoid duplicating content that already exists on an agency website. But prepare users with the information they need before they click the deep link where you’re sending them.
  • Make each link to an agency a call-to-action that starts with a verb. Link the whole phrase.

Alerts

Alerts highlight important or time-sensitive information.

  • Deadlines or urgent content fits well within an alert.
  • Use numerals (1, 2, 3) instead of spelling out numbers inside an alert.
  • Anything less urgent can go into an info box.

Info box

An info box breaks out important information so that readers can skim it quickly.

  • Numbers or important takeaways can go into an info box if they aren’t time-sensitive
  • For example, telling state employees they get 1 personal holiday and 1 holiday credit in 2020
  • Use numerals (1, 2, 3) instead of spelling out numbers inside an info box to make it easier to scan

Lead class text

Lead class is a design style in CSS that makes text larger.

  • Use lead text sparingly to highlight information that’s important to users
  • Try not to use more than one paragraph of lead class text per page