Digital Services Style Guide

For writing in general, always refer to the Associated Press Stylebook. However, here are some recommended guidelines.

Acronyms

Use words that everyday members of the public will know. Acronyms can often confuse users. If you must use acronyms, spell out the words the first time you reference it.

Active Voice

Writing should be direct and engaging. This helps keep content simple and concise.

A fun way to remember this is adding “by Willie Nelson” after the verb in the sentence. If the sentence makes sense, it’s passive voice, which should be avoided.

Another day was selected (by Willie Nelson) for the Council meeting.

If you add “by Willie Nelson” after the verb, and it doesn’t make sense, it’s active voice.

City Council selected (by Willie Nelson) another day for their meeting.

Learn more about federal government guidelines for using active voice.

Bullets

Long paragraphs of text can be tiring to read, bullets help make content scannable. However, avoid using bullets if it’s only 1–2 bullet points as that can feel impersonal and terse. Formatting the content into a sentence can be friendlier and easier to read and remember.

  • Avoid:
    • Room 241
    • Starts at 8 p.m.
  • Do:
    • The class starts at 8pm in Room 241.

Capitalization

  • Do capitalize proper nouns, including names of individuals, places, and agencies.
  • Don’t capitalize personal titles unless they precede a name.
    • “Please call the city manager.”
    • “Nice to meet you, City Manager Smith.”

Complete Sentences

  • Write in complete sentences. This ensures you are communicating a complete and clear statement to residents.
  • Avoid writing sentence fragments.
    • “Shows no signs of improving after the input session.”
  • Avoid writing run-on sentences.
    • “The City will be requesting resident input on the new master plan residents have asked for meetings to be held after 6 p.m. in multiple locations to have all voices heard.”

Conscious Style

  • Use “older person” rather than “senior” or “elderly.”
  • Avoid using “citizen,” as many government programs serve non-citizens. Instead, use:
    • People
    • The public
    • Users
  • Use gender neutral text, like “they” and “them.” Change “fireman” to “firefighter.”

See tips from the Conscious Style Guide to create inclusive content.

Context

When users visit your page, they should be able to understand what is on the page, the purpose of the page, and what actions they can take. Avoid writing your content in a way that assumes the user is already familiar with your content.

A user should easily be able to answer the question: “What is this?” If they have to read the entire page first to understand what it is, then the page is lacking context.

For example, let’s say a department creates a page to offer classes to residents, the content below would not be clear as to what the page is about from first reading it:

Learn

  • Grow your skills.
  • Become a better you.
  • Our instructors are certified and qualified. Learn more.

A better way to start this page and give this content context would be:

Take a Ceramics Class

Learn hand-building techniques for sculpting clay, and create beautiful works of art in this 4-week course. Beginners are welcome. The next class starts March 20. Sign up for the ceramics class here.

Design-Agnostic

A page’s layout will change depending on the size of the user’s device. It’s important to not include any language that references an item’s position on a page to ensure the content doesn’t conflict with what the viewer is seeing on their device.

  • Avoid: “For time and location, view the class details to the right.”
  • Do: “For time and location, view the class details.”

One of the easiest ways to ensure the longevity of your content is to make sure it doesn’t specifically reference the design of the page. As layouts or colors and type change in the future, having design-agnostic content will ensure that every time a design change is made, a content change isn’t also needed.

  • Avoid: “Click the green “Enroll” button to start the enrollment process.”
  • Do: “Click the “Enroll” button to start the enrollment process.”

Emphasis

  • Don’t use all caps, as it looks as if you are yelling at the user.
  • Avoid italics, as they are hard to read online.
  • Don’t use underlines, unless it is for a hyperlink.
  • Don’t center text, as it is hard to read.
  • When using bold to emphasize text, use it sparingly.
  • Do not use colored text.
    • The color of the text has been carefully chosen to meet accessibility guidelines. By adding a custom color or by using colors differently from other parts of the site, you risk making the content inaccessible and confusing for users.

Headings

Use header formatting to break up content. Do not use bold for headings. Users with visual impairments use screen readers to read websites, and screen readers do not recognize bold as a heading.

Lists

If there are instructions where only one action is acceptable, format them into a list and lead all non-primary options with “Or”. By having “Or” as the first word on subsequent actions, it makes it clear for people scanning a list that there are limited options.

  • Avoid:
    • Do this or
    • Do this second thing or
    • Do this third thing
  • Do:
    • Do this,
    • Or do this second thing,
    • Or do this third thing.

Numerals

  • Spell out numbers one through nine, and use numerals for numbers 10 and greater. This is true of ordinal numbers.
  • Spell out first to ninth, and capture 10th or greater with numerals.
  • For amounts of money in cents or greater than $1 million, use numerals followed by words:
    • 7 cents or $1.9 million
  • For amounts of money less than $1 million, use the dollar sign: $20.
  • In titles, subheadings, and interface labels, use numerals instead of spelling out numbers.
    • “7 Grants for Local Small Businesses”

Phone Numbers

Most mobile devices are able to automatically detect a phone number and turn it into a clickable link. This makes it easy for users to simply tap on the number to initiate a call instead of having to manually type in a phone number.

  • Avoid: Letters for words, like “To call the Help Desk, call (512) 974-HELP.”
  • Do: “Call the Help Desk at 512-974-4357.”