Writing

Reflect User Needs

Write to address the user; help them find the information they need quickly and easily. Ask yourself:

• Who is the primary audience for this page?
• What’s the point of this page?
• What’s the most important takeaway?

Use Plain Language

Government sites are for everyone. Content should be as plain and straightforward as possible.

• Use short sentences and paragraphs.
• Avoid government jargon or department/division jargon.
• Use pronouns.
  • The user is “you.”
  • “We” are City government and staff speaking to the user.
• Use active voice.
  • “The mayor held a community input meeting.” NOT “A community input meeting was held by the mayor.”

Learn more about federal government plain language standards and content guide.

Create Smart Structure

Reading online is a very different experience than reading print. It is important to structure content so it’s easy for users to digest.

• Put the most important information first.
• Break text up using headers, bullets, and numbered lists.
• Don’t use FAQs.
  • They are hard to read and search.
  • They often duplicate other content on your site.
  • They mean that content is not where users expect to find it—it needs to be in context.

Voice

When writing City web content, your voice should always be:

• Professional
• Conversational
• Accessible
• Instructive

Tone

Voice is constant, but tone is variable. Choose your tone based on the content and context. Your tone will be more direct and official when writing a City memo in comparison to a more enthusiastic, relaxed tone for a blog post about a children’s event.

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.

• Passive: “An outdoor event was held by the department.”
• Active: “The department held an outdoor event.”

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.”

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.

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. See “Accessibility.”

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.”