ODI’s style guide

These are the Office of Data and Innovation’s conventions and standard terms for writing. Our content design principles provide general guidance in how to write well.

Acronyms

Write out the full name of something the first time you mention it. Follow with the acronym in parentheses. Use the acronym for any other mentions.

Capitalize acronyms. Do not use periods between letters.

When using an acronym to refer to another state department, follow their convention. If in doubt, look at their website to find out how they abbreviate their name.

Capitalization

Always use sentence case. It’s easier to read and understand. Only capitalize proper nouns and the first word of a sentence or bullet.

When a word or phrase could correctly be written in title case or sentence case, default to sentence case.

When writing out a URL, use lowercase letters. But if it’s the first word in a sentence, capitalize the first letter.

Capitalize the suffix for time of day, and add a space before it.

When creating a link to a page or document on another website, use the same case for the link text that the visitor will find when they use the link.

When making a bulleted list, capitalize the first word in each bullet.

Dates

Write out the month in a date.

Do not use only numbers, which can lead to confusion. Some cultures interpret 9/5/2020 as May 9, 2020 instead of September 5, 2020.

Formatting

Bulleted list

Use bulleted lists for a list of items that are related. They break up long blocks of text into shorter, easier-to-read lists. Do this wherever you have 2 or more nouns or verbs in a series.

Give context for your list with a lead-in sentence followed by a colon.

• Capitalize the first word in each bullet.
• Decide if your bullets will all be complete sentences or fragments. Do not mix both within one list. This confuses people.
  • If your bullets are complete sentences, end them with periods.
  • If your bullets are fragments, do not end them with periods.
• Do not make a list of more than two levels. This is hard for people to read. On websites, this often cramps text against the right margin on mobile devices.

Buttons

On a website or digital service, use a button with a form or to highlight something people may want to do.

• Be short, descriptive, and distinctive.
• Start with an active verb like Apply, Submit, or Search. This keeps the focus on what people need to do.

Buttons make it easier to find and take actions.

Headings

Use headings to break up blocks of text and make your content scannable.

People scan content, especially online, rather than reading every word. When there are large blocks of solid text, they often scan in an F-shaped pattern. This is inefficient and makes what they’re looking for easy to miss.

Headings serve as guideposts. They help people know which parts of the page they want to read more closely. Headings enable more efficient scanning, which looks like a layer-cake pattern.

To make your headings effective:

• Keep them short.
• Use sentence case. It’s easier to read and understand.
• Order headings (and your content) by priority. Start with what’s useful to most people and end with the information the fewest people need. If they are steps, go from first to last.
• Don’t use punctuation.
• Don’t make your heading a full sentence.
  • Example: What we do is better than ODI does many things to help state departments.
• Don’t write headings as questions. Convey certainty whenever you can, not uncertainty.
  • Example: How the DIF helps is better than How does the DIF help?
• Don’t skip heading levels. For example, don’t go straight from H2 to H4. Each level has its own style. Using levels consistently makes a good experience for readers. This also helps people using screen readers.
• Nest heading levels appropriately. For example, H3s can be used for content relevant to the H2 above it. But don’t go past H4. That much nesting is hard for readers to follow.

Law citations

When referencing a law, use this format: Chamber Bill number (author’s political party affiliation abbreviation, author last name-author’s city), bill title.

If you’re unsure of the author’s city, use CalMatters’ legislators directory. Use California Legislative Information to find the bill title.

If you mention a bill from that chamber later in your text, put the abbreviation AB or SB in parentheses after the first use. Follow our acronym rules.

If citing a law in a list of references, use this format: Title, chamber abbreviation-number, California Legislature, legislative body, year. LegInfo URL

Links

Links are embedded in text instead of standing alone.

• 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.
  • Example: A link named Quarantine and isolation goes to a page named Quarantine and isolation.
• Do not use See more, Learn more, Here, or View more in link names. They do not give people a good idea where they’ll go. Some of these phrases also assume everyone can see.
• Limit the number of links. Too many links make the text hard to read. If you have several relevant links, put them in a bulleted list after your main text.
• Have links support comprehension, not disrupt it. People often open links when they come to them. Do not link until it’s alright to send the person away (after you’ve conveyed your point).
• Open links in the same tab and window. Only open content in a new tab or window when there’s a good reason to do so. Give people warning when a new tab or window will open. This is especially important for people on mobile devices. Pages that open in new tabs can confuse people and disrupt their experience.

Notes and disclaimers

When info (especially data in tables or graphs) needs an explanation, follow it with a note to provide clarity. Putting notes next to what they explain makes it easy for people to get more information if they want it. Make the note smaller to signal to the reader that it is secondary info. This makes it easy for people to skip the details if they want.

Numbered list

Use numbered lists when you want to show information in a particular order. The numbers help people know there’s an order. They guide readers by providing a start and end. Do not use a numbered list if order does not matter.

If you’re walking people through an important step-by-step process on a website, use a step list component. It lets you add detail to each step and makes them more readable.

Webpage titles

Browsers show a page title when you hover over the page tab. It helps people know what’s in a tab on their browser.

Make the title the same as the H1 of the page, followed by a pipe and the site name. This gives people a full understanding of the page.

Webpage 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 Request a birth certificate would become /request-birth-certificate.
• Do not make Prepare for a wildfire into /prepare-wildfire. This has a different meaning.
• If your URL feels too long, consider shortening the page’s H1. Make sure both give enough detail so people know what the page is about.

Use the site map to build the URL. If the birth certificate page lives under a page called Services, the URL would be: alpha.ca.gov/services/request-birth-certificate.

Numbers

Abbreviations

Thousands (K)

Write out the number. This is clear to people, even after translation.

When writing numbers with limited space (like labels in a chart), use a K instead of writing out the full number.

For rates that use 100,000 as their base, use per 100K.

Millions (M)

For exact numbers where every digit is important, write out the whole number.

For round or approximate numbers, write out the word million. Use up to one decimal point. Do not add .0 to the end of a number. This is extra text that does not increase understanding. Just use the whole number.

For rates that use million as their base, write out the word million.

When writing numbers with limited space (like labels in a chart), use an M instead of writing out the full number.

Commas

Use commas in numbers over 999. People have trouble understanding more than three numbers in a row. Commas break up the number and make it easier for people to read.

Decimals

Use decimals only when you need to. This reduces the amount of numbers people have to read. 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 when reporting data.

Do not use 0.0.

Use 2 decimal places if you’re writing a price that isn’t a round number.

Fractions

Write fractions using a slash. This is more accurate than using decimal places. It’s also easier for people to understand.

Numerals

In sentences, use numerals for all numbers, except for one. People recognize numerals more easily than numbers written as words. This is especially true when people scan text. Scanning is common when reading on a screen.

If you have to start a sentence with a number, write it out. Try to avoid starting sentences with numbers so you can use numerals.

Telephone numbers

Use hyphens to separate the area code, first 3 digits, and last 4 digits. Do not use parentheses. When it serves the user (like on a webpage), make the telephone number a link.

Times

Use AM and PM with times. Put a space between the time and AM or PM. Convert times to the Pacific time zone. Unless your target audience is out of state, do not state the time zone since California is only in one time zone.

If you use a dash when writing a time range, put a space between the dash and the times.

Styling

Bold

Use bold for emphasis, but sparingly. When too many things are emphasized, nothing stands out.

Do not add bold to a heading. Heading style is usually set through a template for consistency throughout a document or site. If you need to change the heading style, do that in the template.

On websites, adding bold tags to a heading can cause it to appear in the wrong font.

Italics

Use italics sparingly, as they make text harder to read. But there are times when italics are useful.

Italicize titles, especially when they are in sentence case.

Italicize words in a foreign language.

Do not use italics for:

• Emphasis - use bold instead
• Captions for images or charts - use smaller text instead
• Whole paragraphs of text
• Quotes

Larger introductory text

On webpages, use larger introductory text on the first paragraph to state its most important takeaway. This sets people’s expectations about what they’ll find on this page and if it’s valuable to them.

Making this text bigger emphasizes its importance and helps people see it. But because this text is larger, keep the paragraph brief.

Only use larger introductory text in the first paragraph on a page.

Underline

Do not underline text. On websites or documents shared online, it makes text look like a hyperlink. Use bold for emphasis instead.

Words

Alaska Native

Use Alaska Native instead of Inuit or other Tribe names when referring to people descended from the native peoples of Alaska. This follows federal Bureau of Indian Affairs language guidelines. This may be abbreviated to AI/AN in charts as part of the American Indian/Alaska Native federal demographic group.

alright

Use alright as a synonym for OK. Spell it this way and not all right.

American Indian

In charts only, use American Indian instead of Native American when referring to people descended from the native peoples of the continental U.S. This follows federal demographic language (abbreviated to AI/AN). In all other cases, use Native American.

Asian American

Use Asian American when referring to people of Asian descent. Capitalize this wherever it appears in a sentence.

Black

Use Black when referring to people of African descent. Capitalize this wherever it appears in a sentence.

CA.gov

Use CA.gov when writing about the ecosystem of state websites or the State of California homepage. This follows the California Department of Technology style. Use ca.gov when writing a URL, like digital.ca.gov.

county

Use county in lowercase when referring to a level of government.

Capitalize County if it starts a sentence.

Capitalize County when referring to a specific county.

When referring to more than one county, do not capitalize counties.

data

Write data as if it’s singular. This sounds more natural and conversational than writing it as if it’s plural.

directorate

The collective term for ODI’s director and chief deputy director.

disability

Use people with disabilities instead of disabled people. This affirms the humanity of people with a disability instead of defining them by their condition.

If writing about people who share the same disability, be specific.

division

The major organizational units of ODI are divisions. They are:

• Operations
• Strategy, Partnerships & Training
• CalInnovate
• CalData

e.g.

Do not use Latin abbreviations like e.g. (which stands for exempli gratia, or “for example”). Many people do not understand them. Use for example instead.

executive team

We use executive team to collectively refer to ODI’s senior leadership team and their direct reports (often deputy directors).

for example

Use for example instead of e.g., which is an abbreviation of the Latin phrase exempli gratia. This translates to “for example.” Writing out for example makes it clear to the reader what you mean.

Governor

Always capitalize the word Governor, either with or without their name. This follows the Office of the Governor’s style.

homelessness

Use people who are homeless or people without homes instead of the homeless or homeless people. This affirms the humanity of people in this situation instead of defining them by their present situation.

i.e.

Do not use Latin abbreviations like i.e. (which stands for id est, or “that is”). Many people do not understand them. Use that is instead.

Latino

Use Latino instead of Latinx or Hispanic when referring to people of Latin American or Spanish descent.

LGBTQ+

Use LGBTQ+ instead of LGBTQ or similar initialisms. This is the prevailing convention among state departments.

Multi-race

Use Multi-race only in dashboards or chart notes to refer to those of more than one race. Do not capitalize the “R” in race.

Native American

Use Native American instead of American Indian when referring to people descended from the native peoples of the continental U.S. This follows the California Native American Heritage Commission’s style. The one exception is in charts, where American Indian is used to match federal demographic language.

Native Hawaiian

Use Native Hawaiian when referring to people of Hawaiian descent. This follows the federal Department of the Interior’s style. It can be abbreviated as NHPI in charts as part of the Native Hawaiian/Pacific Islander category.

Office of Data and Innovation

When spelling out the full name of the office, use the word and. Do not use an ampersand (&).

OK

Use OK instead of okay.

Pacific Islander

Use Pacific Islander when referring to those descended from the peoples of Oceania. This follows federal demographic language. It can be abbreviated as NHPI in charts as part of the Native Hawaiian/Pacific Islander category.

senior leadership team

The collective term for ODI’s:

• Director
• Chief deputy director
• Chief data officer
• Chief counsel
• Special advisor to the director

senior management team

This term includes everyone with programmatic oversight and decision-making authority. It includes:

• Executive team
• Management staff
• Select individual contributor staff, like the Government Relations Manager and Legislative & External Affairs Manager

staff

We call everyone who works at ODI staff. We modify this term to refer to specific groups within ODI.

• Staff who do not manage people are individual contributor staff.
• Staff who manage people are management staff.

state

Use state in lowercase when referring to:

• The state of California as a place
• A level of government

Capitalize State if it starts a sentence.

Capitalize State when using the term State of California to refer to our state’s government.

team

ODI calls its base organizational unit a team. Teams make up divisions.

that is

Use that is instead of i.e., which is an abbreviation of the Latin phrase id est. This translates to “that is.” Writing out that is makes it clear to the reader what you mean.

Tribe

When referencing a specific Native American community, capitalize Tribe or Tribal as a sign of respect. This follows federal Bureau of Indian Affairs language guidelines. In other contexts, do not capitalize.

users

The word users should be used only when you need to specifically indicate those who use an item or tool.

In most cases, it’s better to call them people. This affirms their humanity instead of seeing them only as users of a service.

Do not use the word users where it can give the wrong meaning, such as in the context of drugs, addiction, or recovery.

white

Use white when referring to people of European descent. Do not capitalize it unless it is at the start of a sentence.

zip code

Though the United States Postal Service capitalizes it ZIP Code, use zip code. Most people don’t know that zip is an acronym. Using capital letters distracts readers. The unexpected capitalization makes them pause and question the content. The lowercase zip code is easier for people to understand and read.

Technical glossary

The engineering team uses these abbreviations and capitalizations for consistency.

• CMS - content management system
• CSS - cascading style sheets
• GitHub - code repository platform
• JavaScript - language
• Markdown - language
• Microsoft Edge - browser
• npm - software registry
• Nginx - web server
• Solr - search platform
• Sass - language
• SCSS - syntax
• WordPress - a CMS
• jQuery - a JavaScript library
• CA.gov - see entry in Words section
• Bootstrap - a front end toolkit

Can’t find what you’re looking for?

This guide doesn’t cover everything. If it doesn’t answer your question, here are resources the content team uses.

Inclusive language

• Start with Atlassian’s inclusive language guide. It’s good general guidance. Their do’s and don’ts are helpful.
  If you want advice on how to talk about a specific group, try the CDC’s Preferred Terms for Select Population Groups & Communities. It includes many terms that often come up in government work.

Other style questions

For all other style questions, we use AP Style. It’s behind a paywall. But you can ask the ODI content designers questions. They have subscriptions to the AP Stylebook.