Updated

Content style guide

We write for all Californians. Our content bridges the gap between Californians and the information and services they need.

Our voice

We are partners of Californians, helping get them the services they need.

We areWe are not
A source of truthExpressing opinions
Information providersService providers
Welcoming to everyoneOverbearing
FriendlyFake
OfficialCold or distant
ConversationalDisrespectful
StraightforwardBlunt
EmpatheticApathetic
Sensitive toward othersPretending to save people or know everything about them

Content about emerging situations

Give people a sense of calm, control, and purpose. Make people feel they have just enough information to act. Give them the most widely-applicable and urgent info. For specific info, link to state agency content.

Get an authoritative state-level response up first. Fight misinformation by providing the truth directly and clearly. When that’s up, focus on questions you imagine people asking.

Ask these questions when writing content:

  • Is the state the right authority on this?
  • Does another agency (federal, state, or local) have more detailed or current data?
    • If so, link to them.
  • If information will change over time, link to where it will be kept up-to-date.
  • Does this content reflect what is currently true?
    • Remove things like intentions or hopes.

Assume that everyone’s reading level is a few grades lower due to stress. Readers are juggling lots of new information, disruptions, and distractions.

  • Use:
    • Short sentences
    • One or two syllable words
    • Simple sentence structure
    • A clear hierarchy of information
  • Do not use special terms. People probably won’t know what they mean.
  • Avoid repetition, even when there are slight differences.
  • Keep conditional sentences (if/then) to a minimum.

Our style

We write content that’s user-centered. It’s:

  • Clear
  • Concise
  • Accessible

Focus on user needs

Give users what they need, not what you want them to think about the government or agency. Put the content they most want first.

Requirements, not advice

People come to a government website to find out what they need to do. Do not give advice or make suggestions. Use should as little as possible.

Plain language

Plain language is clear and accessible to everyone, including readers with cognitive disabilities and limited English fluency.

  • Choose simple words when possible.
  • Explain jargon when you have to use it.
  • Spell out acronyms when first used. Put the acronym in parentheses after the first use if you use it later.
    • Spell out the acronym the first time it is used in an accordion even if it’s been used earlier in the page. We do this because accordions can show up as a quick answer where they will not have the benefit of the page context.
    • Do not spell out CDC. The acronym is better known than “Centers for Disease Control and Prevention.”
  • Use positive phrases instead of negative ones. They’re easier to understand.
    • Example: write lack instead of do not have.

Usage list

  • We use Latino instead of other terms like Latinx or Hispanic. This conforms with standard demographic terms we use in our data visualizations.

Clear sentences

  • Use active voice and strong verbs.
  • Turn gerunds into verbs where it makes sense.
    • Example: write help instead of helping.
  • Write in present tense.
  • Do not use pronouns like this, those, and these or references like as above. They’re vague. Restate what you’re referring to.
  • Write out or abbreviate months in dates. Some cultures interpret 9/5/2020 as May 9, 2020, instead of September 5, 2020.
  • Use numerals instead of spelling out numbers.
    • Use commas in numbers over 999. This helps people understand order of magnitude.
    • Only use decimals when you need to. Only go to one decimal place in most situations.
    • Use more than one decimal place when using this rule or rounding would cause you to show a value as 0 when it is not truly 0. This most often comes into play with data reporting.
    • Write 0 without any decimal places.

Reading level

Write at a sixth grade level or lower. Some content may not be able to reach this goal, but always look for opportunities to improve through simpler words and shorter sentences. Check reading levels with the Hemingway Editor. Eliminate very hard to read sentences and minimize hard to read sentences.

Be concise

Use short sentences and paragraphs. They’re easier to read and accessible for all readers, regardless of reading level.

  • Aim for one thought per sentence.
  • Vary the lengths of your sentences and paragraphs to sound natural.
  • Remove words that don’t add value.
    • Example: don’t say please when telling a reader what to do.
  • Be direct and confident.

Organize content by importance

Put the most important content first on a page. This is often the content that applies to the most people. Content that applies to the least people (like specific populations) last.

Keep it conversational

Write how you speak. Read your writing out loud to hear how it sounds.

  • Imagine each period as a breath and each comma as a pause.
  • Use common contractions like you’ll, it’s, and we’ll.
    • Do not use contractions with not like don’t and aren’t. When skimming, readers see do and don’t as the same.
    • Do not use uncommon contractions like this’ll, y’all, and ain’t.
  • Where it makes sense, start sentences with And or But to show the relationship between content and add a smooth transition.
  • Refer to people as you, and the government or agency as we. Don’t use me or my. It’s unclear if me refers to the readers or the writer.

We use AP Style with a few differences. We use the serial comma (also called the Oxford comma) to reduce confusion. It’s the comma that comes before and in: We brought apples, bananas, and oranges.

Accessibility

We write for all Californians.

Keep the following people in mind when you write:

  • Californians with limited financial resources
  • Californians without internet access
  • Californians who live in difficult housing situations (like those with domestic violence)
  • Californians struggling with depression or suicide
  • Californians without a fixed address
  • Californians with disabilities
  • Communities of color
  • Immigrant Californians
  • Tribal communities
  • Californians with limited or no English fluency
  • Rural Californians

When discussing benefits and supports, state:

  • Minimum requirements
  • Any income restrictions
  • If it’s available regardless of immigration status, including:
    • How their personal information is protected
    • Which immigrants are eligible
    • If it counts under the public charge rule

If writing for a specific audience, consider what languages the content should be translated into.

Get to know the people who use your site

Google Analytics and Search Console shows you the words people are using online. They provide keywords people use to find a page and what they’re trying to find on the page. Modify the content or metadata to mirror their language.

Work with user researchers to do deeper testing to understand how well people can complete tasks and discover needs you may not know about.

Structure and formatting

Well-structured content is easy to read and accessible.

Headings

Clear headings make pages easier to scan and understand.

  • Use sentence case. Capitalize the first word and proper nouns. It’s friendlier and helps readers recognize proper nouns.
  • Make the name of your page an h1 header. Only use one h1 header per page.
  • Use header levels in ascending numerical order. Do not skip steps. It’s OK to repeat header levels.
  • Always have at least one line of text between headers.
  • Do not use header tags for full sentences or non-header body text.

Check your heading structure in Google Docs. Select View and Show Document Outline to confirm they nest appropriately.

Lead class text

Lead class text makes text larger. Use it to explain the service or topic at the top of the page, underneath the h1. Only use one paragraph of lead class text per page. Use <p class="emphasized">the text you want</p> in Wordpress to create lead class text.

Titles

The title appears when you hover over the page tab in a browser. It helps users change between tabs on their browser.

Make the title the page heading followed by a hyphen and the site name. This gives users a full understanding of the page. Here’s an example, including the coding tags: Content guide - <a href="http://Alpha.CA.gov" target="_blank" rel="noopener noreferrer">Alpha.CA.gov</a>

Page URLs

Use the h1 of the page to create your URL. This helps search engines find the page.

Replace spaces in the title with hyphens so search engines can read them. 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.
  • Don’t make Growing up with diabetes into /growing-diabetes. This has a different meaning.

Use the site map to build the URL. If the licensed contractor page lives under a page called Services, the URL would be: alpha.ca.gov/services/hire-licensed-contractor-home-improvements

Any time the site name is spelled out in content, make it a hyperlink to the homepage.

Bold, italics, underlining

Make important information or keywords users search for bold. We do not use italics for emphasis.

Do not underline content. Web browsers highlight links automatically. Underlining non-link content confuses readers.

Use a button with a form or to highlight something the user wants to do. Links are embedded in text instead of standing alone.

  • Link to webpages instead of PDFs as much as possible. Webpages are more accessible across devices, more easily searched, and less likely to break.
    • If you must link to a document, make it a PDF if possible. Word documents, Excel sheets, and PowerPoint presentations require software to view them that people may not have.
    • Indicate if the link is going to a file by providing its extension (like PDF, DOC, or PPT) so people can choose if they want to download it.
    • Use the PDF link class to format links to PDFs.
  • Make the link title match the title of the destination page as much as possible. This helps people know they arrived in the right place.
  • When creating a button, be short, descriptive, and distinctive.
  • Start with an active verb like Apply, Submit, or Search. This keeps the focus on the user’s needs.
  • Do not use See more, Here, or View more. They do not give the user a good idea where they’ll go. These phrases also assume everyone can see.
  • Limit number of links so as to make the text more readable. If you have several relevant links, put them in a bulleted list after your main text.
  • Have links support comprehension, not disrupt it. Do not link until it’s all right to send the user away (after you’ve conveyed your point).
  • Open links in the the same tab and window. Only open content in a new tab or window when there’s a good reason to do so. Give them warning when a new tab or window will open.
    • See the examples page to see what code to use in WordPress to create linked to other sites and PDFs.
  • When you end a sentence with a link, do not include the period in the hyperlink.
  • Always create dial links for phone numbers. This allows users, especially mobile users, to dial the number with one click. The WordPress format for the link is tel:123‑456‑7890, and the HTML is <a href="tel:123‑456‑7890">123‑456‑7890</a>.
    • Use non-breaking hyphens when creating these hyperlinks. These allow phone numbers in Arabic translations to work. The hyphens above are non-breaking. To be sure you’re using a non-breaking hyphen, you can also use &#8209;.

Notes and disclaimers

When info (especially data in tables or graphs) needs an explanation, follow it with a note to provide clarity. Make the note smaller to signal to the reader that it is secondary info. In WordPress, use this code in the HTML view to create smaller text: <p class="small-text"> … </p>

Content types

Some content comes across better in non-paragraph form. Bullet points, alerts, and info boxes also make pages easier to scan.

Bullet points

Use bullet points for a list of items that are related. Only use bullet points if there is more than one item in the list.

Put a period at the end of a bullet point if it’s a full sentence.

  • Ask family and friends for contractors they recommend.
  • Search online and read reviews, but consider the source.
  • For repairs, your homeowners insurance might cover the cost and suggest contractors for you.

Do not add a period if the bullet point is not a full sentence. Capitalize the first word of every bullet point.
Ask the contractor to share the name of their insurance carrier and copies of both their:

  • Workers’ compensation insurance
  • General liability insurance

Be consistent with whether your bullet points are sentences or not.

Numbered lists

Use numbered lists when a user needs to do tasks in a certain order, like a process. They’re especially helpful if the steps happen across different agencies.

  • Start each task with a verb.
  • Provide a high-level summary in the task. Put smaller details in the Show/Hide text.
  • Keep the description short, no more than a few paragraphs.
    • If it cannot be condensed, make a guide instead.
  • Give each number an ARIA label so screen readers can read them aloud as step one, step two, and so on.
  • Link to content that already exists on an agency website. Do not duplicate it. Prepare users with the information they need before they select the link.

An example of a numbered list is Hire a licensed contractor for home improvements.

Questions and answers

People often think in terms of a question they have. Creating anticipated questions and providing answers to them is an effective way to meet their needs.

When creating a question and answer section, just call it Questions and answers. Don’t add any information like Questions and answers about financial help. If questions and answers cluster around certain topics, create subheaders to organize them.

To prevent a question and answer or other accordion from showing up in search results on covid19.ca.gov, add this class to the accordion title block (which will already have the class wp-accordion): js-qa-exclude

Guides

A guide is a comprehensive summary of complex information. It usually spans multiple pages. Side navigation lets users move between pages.

An example of a guide is Apply for unemployment insurance.

Smart answers

A smart answer gives the user an answer that’s specific to their location or situation. Users enter info into one or two form fields.

  • Be clear about any limits of the answer.
    • Example: If we can only look up cities in California, share that up front instead of through an error message.
  • Give the button a descriptive term that anticipates the info the user will receive.
    • Example: Check your water instead of Enter.
  • Make error messages proactive instead of assigning blame.
    • Example: Please enter a city in California instead of You entered a city outside of California.

Examples of smart answers are Find the minimum wage in your city and Check lane closures for your trip.

Guided answers

A guided answer takes users through multiple questions to provide an answer tailored to them.

  • When the questions are on separate pages, a Next button is helpful. The final button should convey the outcome, like Check if you qualify.
  • Give users a way to get back to the previous question. Separate it from the buttons used to answer questions.

An example of a guided answer is Check if you can get a discounted phone service.

Checklists

Use a checklist when you want a user to be able to select multiple options from a list. Use radio buttons if you only want them to select one option.

Forms

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

  • Create titles for each field. Do not use placeholder text that disappears when the user starts typing. It’s hard to remember what belongs in the field or ensure it’s accurate. Placeholder text also is not accessible.
  • Display valid options as a user starts typing to confirm what they can choose.
  • Add helper text that appears outside the field if someone makes an invalid entry.
    • Example: Please enter a nine-digit phone number such as 555-555-5555.
  • Include a button to explain what type of results users will get.
    • Example: Search for your city.

Alerts

Alerts highlight important or time-sensitive information like deadlines.

Info boxes

Put important information in an info box to help readers find it quickly while skimming. If the content is urgent, use an alert instead.

Page indexes

An optional way to give users an outline of a long page is to add a page index at the top.

  • Start with a brief sentence or two that states the most important takeaway on the page. Give this paragraph the “emphasized” class.
  • Follow with the text On this page: that introduces the index. Make it in Paragraph form with an “h3” class (not an H3 form, for accessibility reasons).
  • Then add a bulleted, bolded list of the h2 headers on the page. Do not link subheaders. If something is important enough to appear in the page index, elevate it to an h2 header.
  • Give the bulleted index list the class “toc” which will give it carat bullets and consistent styling.
  • Make each h2 header an anchor link, and link each item in the index to its corresponding header.
Created and maintained by Office of Digital Innovation