Writing for the City of Oakland

The City of Oakland is committed to accessible web experiences for everyone, regardless of disability, device, or language. City web pages must meet Level AA conformance under the Web Content Accessibility Guidelines 2.1 (WCAG 2.1). Use this writing guide to learn how to meet that standard, step by step.

Goals and Principles  | Organize Your Content | Format Your Text | City-Specific Style | Writing about People 

Goals and Principles

City of Oakland content needs to be accessible to all members of the Oakland community.

All the content published by the City of Oakland should meet the standards outlined below. 

1. Simplicity. All written communication should help community members access and understand City services, policies and procedures. To this end, writers should try to use short sentences and simple words to convey information. 
2. Equity. City communications should touch everyone in our community. We reach the greatest number of people in our community by using clear language, translating our content into multiple languages, using various communications channels, and assessing ourselves with benchmarks. 
3. Trust. City of Oakland writing should convey a sense of authority and respect--we want to be a trusted source of information for the Oakland community. We accomplish this by ensuring our information is accurate and making it clear that the City of Oakland is the author of City content. 
4. Access. We create non-text alternatives, large print, speech/audio options, and symbols, and can be accessed using all user agents and assistive technologies. We also work with City of Oakland ADA Programmatic Access Coordinator to ensure we’re complying with the law. 

In the City of Oakland, we use the Associated Press Style Standards (AP Style Guide) with a few exceptions noted below. Following these rules helps us keep our writing clear and consistent. Please note that the AP Style Guide does not use the serial comma. Additionally, you can refer to our Grammar Tips Sheet or use a free online grammar check called Grammarly. 

Voice and Tone 

Content creators for the City of Oakland should write in a way that is friendly and informative but also conveys authority and builds trust. Use a conversational tone when you’re writing and don’t use City-specific language or jargon. Imagine that you are having a friendly conversation with your reader and that you are in a position to provide them helpful information. You understand the topic at hand and are there to help. Never assume readers have a deep understanding of a subject, and when you are describing a complicated issue, explain the point in clear language and, when necessary, provide context for the topic. 

Address the user as “you” when possible. 

• “You can contact the Oaklanders Assistance Center by phone or email.” 

Make direct appeals to users to get involved or take action. 

• “Pay your parking ticket.” 

Use positive language 

• Yes: “Please pay by personal check or cash.” 
• No: “No credit cards accepted.” 

Be polite and clear. 

• Yes: “Please look for signs, curb colors and stickers on meters.” 
• No: “Be sure to obey parking restrictions indicated by posted signs.” 

Use an active Voice. 

• Yes: You can pay your ticket at the Parking Citation Assistance Center. 
• No: Parking tickets are paid at the Parking Citation Assistance Center.  

Match Your Tone to the Content 

In the City of Oakland, we write about things ranging from the tragic to the celebratory. Be sure to match your tone to the tone of the topic you are writing. When writing about every day and positive events like community gatherings, celebrations, elections or other good news, use an energetic and enthusiastic tone. 

When you are writing about serious or urgent events like crime, natural disasters, protests, public transit updates or other topics related to public safety it is critical that you write in a way that is unbiased, informative and professional and use simple and concise language. Refer to facts and avoid all speculation. Do not use exclamation points and only include links if they direct the reader to further critical information. 

• No: “Today, there will be a road closure on 14th Street in downtown Oakland. For more information click here.” 
• Yes: “Road closure Aug. 17, 2015, at 14th St., downtown. [link]” 

Readability 

The City of Oakland Web Information Technologies Access Policy requires that writing for the public should be readable by anyone with a 6th grade level of reading comprehension. You should always aim to use words that a ten-year-old could read. You can test the readability of your writing with an online readability tool like the Hemingway App.

Use plain language and choose short, simple words whenever possible to increase the readability of your content. 

You can use contractions such as "you’re," it’s, or "we’ve." Use short words and sentences. Provide just enough details so the user can complete the task. Leave out details that may distract or confuse your reader. Keep the text short and easy for Web visitors to read quickly. Use bulleted or numbered lists if it helps make the information more clear to the reader. 

Avoid Jargon, Idioms, and Acronyms 

Acronyms and jargon are words that only make sense to experts, City staff and other specific groups of people. Avoid using specialized terms whenever you can. Instead, use simple terms that everyone can understand. Where jargon or acronyms are unavoidable, always explain what words mean, write out the full meaning of the acronym the first time it appears, or flag the content to become an item in the City’s online glossary. Examples of jargon, idioms, and acronyms include: 

• Acronyms for the names of City departments: CAO, OAC, OPW, ITD, etc. 
• Names of forms: Form 500, Form 700. 
• Names of technical programs or software: Legistar, Accela, Oracle, etc. 
• Rarely used Latin terms (“inter alia,” “ad hoc”), legalistic prose (e.g., text from the Oakland Municipal Code) and unexplained abbreviations. 
• Idioms, or figurative expressions, such as “state of the art” or “rain or shine” may be difficult for persons who do not speak English as a first language or persons with cognitive or neurological disabilities to understand. 

Glossary

Sometimes when you are writing about specific services, programs, or laws, you will need to use complex language or civic terminology even if you know it will be difficult for your readers to understand. If you need to use a term that has either City-specific terminology or difficult vocabulary, please define the word in the content. 

Additional Style Resources 

AP Style Guide 

The City of Oakland has a free subscription to the AP Style Guide that is available through the Oakland Public Library. 

The Diversity Style Guide 

A free compilation of best practices for writing about people from around the web. 

Grammarly

An online tool that catches common grammatical errors using Chrome. Free download for use with Microsoft Office. 

Hemingway App 

An online writing tool that evaluates your writing for simplicity and clarity. Hemingway will evaluate your text and assess your reading level. Additionally, it provides tips for improving your writing. 

WebAIM 

A resource for making the web and your web content more accessible to users with different abilities. 

The Purdue Owl 

The Purdue OWL is a great resource for writing tips and offers information on how to use proper grammar, capitalization and punctuation. 

 

Organize Your Content 

When writing for a website, it is important to present information in a way that is consistent and easy to understand. If you use headings, they should describe the topic or purpose of the web page. 

Page Titles 

Capitalize the first letter of words in a title unless they are prepositions. 

• Yes: Street Sweeping 
• Yes: Report a Broken Meter 

Headers 

Headers are one of the most important ways that we communicate the structure of our information. Your headers should be as clear and concise as possible. Use action words in your headers whenever possible. 

• No: “Reporting a Problem,” 
• Yes: “Report a Problem.” 

Buttons and Calls-to-Action 

Use sentence case for any button, link, or suggestion that the user do something. A sentence-style capitalization is best because it conveys a friendly tone that invites users to press the button. 

• No: “Pay a Parking Ticket” 
• Yes: “Pay a parking ticket” 

Legal Codes 

Few people will read federal, state or municipal codes in their entirety. Whenever possible, translate critical pieces of municipal code into simple language. Hyperlink to the actual text of the law only when necessary. 

Example: 

• (18 U.S.C. Sec. 2258) 

 

Format Your Text

It is important to use lists and other formatting in a way that is consistent across the website. 

Bulleted Lists 

• When using a bulleted list: 
• Introduce a bulleted list with a colon 
• Capitalize the first letter of the first word of each bulleted item 
• Use consistent construction of each bulleted item 
• End bulleted sentences with periods, not semicolons or commas 
• Do not punctuate the end of bulleted fragments 

Hyperlinks and Hypertext 

You should embed hyperlinks in the text. Screen readers usually inform the reader if a word is a hyperlink, so the words ‘click here’ or ‘link’ are unnecessary. Link text should always describe the purpose of the link. 

For example: 

• Yes: For more information, you can check out Pay a Parking Ticket online.
• No: Click here to learn more about parking in Oakland
• No: Check out how to report a crime: https://www.oaklandca.gov/Public-Safety-Streets/Report-a-Crime
• No: Check how to pay a parking ticket here. 

When creating hyperlinks link titles or nouns that are descriptive of what you are offering to the user. Do not link the verbs. 

For example: 

• Yes: Download passport forms. 
• No: Download passport forms. 

Learn more about how to you hyperlinks in a way is accessible to all our users, check out Web Accessibility in Mind. 

Short URLs 

If you would like to have a short URL so that your content can be accessed more easily, please send a request for one to be created tocomms@oaklandca.gov  with the desired URL in the link. If available, someone from the Communications and Engagement team will create the URL using the built in feature of oaklandca.gov for redirects.  

For example, oaklandca.gov/5after5 was created for the oaklandca.gov/topics/5-after-5 topics page. 

The use of 3rd party URL shorteners such as Bit.ly is discouraged because they are very hard to keep track of over time and don't provide the credibility of the ".gov" address.

Date and Times 

Identify a month by either using its full name or abbreviation 

• Yes: January or Jan. Use a comma after the day of the week, before the date 
• Yes: Tuesday, August 18, 2015. Specify the time of day by using am or pm. 
• No: 5 o’clock, 5 p.m., 5 in the evening 
• Yes: 5 pm 

Phone Number Formats 

Always put the area code in parentheses and then a dash after the next 3 numbers that go after the area code.

• Yes: (510) 238-2107 
• No: 5102832107
• No: 510 238 2107
• No: 510-238-2107

Numbers

Spell out numbers ten and less such as five staff, nine youth or ten teams. 
Use Arabic numerals for numbers over ten such as 21, 99 or 10.5. 

Dollar Amounts 

Use digits for dollar amounts under $999,999 such as $150,000, $4,506.33 
Do not use digits for dollar amounts of $1 million or more such as $2.7 million or $1.41 billion. 

Measurements 

Spell out the words using the imperial numeric system rather than the metric system using inches and feet.

• Yes: 2 feet by 4 inches
• No: 28 inches
• No: 71 centimeters

Decimals 

Place a 0 (zero) before decimals that are less than 1. 
When possible, use decimals instead of fractions such as ½ = 0.50 or ¼ = 0.25. 

• Yes: 0.25
• No: ¼
• No: .25

Percentage 

Use numerals when spelling percentages. Spell out percentage, instead of using the % symbol such as 5 percent 

Serial Commas 

In the City of Oakland, we follow APA style. In writing for the Web, do not use serial commas. (i.e., do not put a comma before the conjunction (and, or, etc.) in a simple series. 

Spaces 

Use one space only after periods at the end of a sentence when writing for the Web. 

Conjunctions

Use “And” instead of “&” 

Instead of using &, spell out the word “and.” 

• Yes: Licensing and Permits
• No: Licensing & Permits

Use "At" instead of "@"

• Yes: The event will be at 6pm.
• No: The event will be @6pm.

 

City-Specific Style 

Department Names 

Department names are officially designated in City Ordinance 2.29. When referring to a department, please use the following naming conventions: 

Capitalize the ‘City of Oakland’ 

Always capitalize “City of Oakland”, “Oakland”, “City” (when it is an abbreviation of “City of Oakland”) and proper nouns. 

• Specific city: The City is at 1 Frank H. Ogawa Plaza - The City’ refers to The City of Oakland. 
• Any city: A city tends to have lively downtowns - ‘A city’ could be any city. 

Form Names

When referencing a form, always give the English title of the form instead of the form number. 

• Yes: Application for Registration 
• No: Form 4002 

Refer to “311” as “OAK 311” 

When referencing our City Call Center, it is important to convey to the public that it addresses services Citywide. 

• Yes: Contact the OAK 311 Call Center for help. 
• No: Contact the PWA Call Center for assistance. 

City Partnerships 

We should only highlight the following partners on the City website: 

• Other governmental agencies 
• Organizations with which the City has a formal, contractual relationship 
• Organizations or events that receive funding from the City 
• Organizations or events that are otherwise sponsored by the City 
• Organizations that contribute to City initiatives that the City wishes to acknowledge.  

Refer to the Oakland Government Ethics Act if you have questions about referencing a group or event with formal partnership language. 

 

Writing about People 

No matter who you are writing for, whether you’re writing for an internal or external audience, it's important to write for and about other people in a way that’s compassionate, inclusive and respectful. 

Community Members 

Oakland is one of America’s most diverse cities. We want to reflect and honor that diversity with our language choices. We refer to our constituency as “community members” instead of “citizens.” We serve residents, business owners and visitors. Unless we are talking about a service that is explicitly only available to US citizens, we don’t use the word citizen. City services are in the vast majority of cases available to people without regard to their citizenship status. 

Businesses choose their customers, but it is the mission of government to serve everyone equitably. As a result, we avoid referring to our constituents as “citizens,” “customers” or “consumers.”

Refer to the people we serve as: 

• “Oaklanders” 
• “Community members” 
• “Constituents” 
• “Community” 
• “Residents” or “Business owners" 

Gender-Neutral Text 

Make sure the text is gender-neutral wherever possible. 

• No: A resident should take out his or her trash.” 
• Yes: “Residents should take out their trash.” 

Gender and Sexuality 

When you write about groups of people, use gender-inclusive language. 

• No: Describing groups of people as “guys.” 
• No: Describing groups of women as “girls.” 

When possible, use neutral terms instead of gendered alternatives. 

• Yes: Server 
• No: Waitress 
• Yes: Businessperson 
• No: Businessman 

It’s OK to use “they” as a singular pronoun. 

Use the following words as modifiers, but never as nouns: 

• Lesbian 
• Gay 
• Bisexual 
• Transgender 
• Trans 
• Queer 
• LGBTQ 

Don’t use the phrase “same-sex” marriage unless the distinction is vital to what you’re writing. If the distinction is not crucial to what you are writing, you should just use the term marriage. 

When writing about a person, use their preferred pronouns. If you’re uncertain, just use their name. For additional guidance about how to write about people, visit the GLAAD Media Reference Guide. 

Age

Only reference a person’s age when it is relevant to what you’re writing. If it is pertinent to your content, you can include your subject’s specific age, offset by commas. 

If someone says, “I’m too old to go back to school,” the age is relevant. You may use age in profiles, obituaries, significant career milestones and achievements unusual for the age. Do not use age for sources commenting or providing information in an official capacity. You may use appropriate background information like the “mother of two young children” or “a World War II veteran” instead of the person’s chronological age. Always get permission from the subject of your writing before you use personal information to describe publicly. 

• Yes: The CEO, 16, just got her driver’s license. 
• No: The CEO is 35 and enjoys sailing. 

Disability 

Only reference a person’s disability when it is relevant to what you’re writing. If you must mention it, always emphasizes the person before the disability. When writing about a person with disabilities, don’t use the words “suffer,” “victim” or “handicapped.” 

• Yes: “She has a disability.” 
• No: “She is disabled.” 
• Yes: “People with disabilities” 
• No: “Disabled people” 

Do not use negative language to describe someone who uses a wheelchair 

• Yes: “Wheelchair User” 
• Yes: “People use wheelchairs for independent mobility.” 
• No: “confined to a wheelchair” 
• No: “wheelchair-bound” 

Hearing

Capitalize the word “Deaf” when you are referring to the “Deaf Community.” 

Vision

You may use the adjective “blind” to describe a person who identifies as having almost complete vision loss or lack of vision. Use “low vision” to describe a person who identifies as having limited vision. 

Mental or Cognitive Conditions 

If you are writing about a person who has a mental, cognitive, or neurological condition, do not use negative or judgmental language. 

Do not use any of the following terms as they are offensive and contrary to the policies and values of the City of Oakland: insane, mentally ill, brain-damaged, crazy, nuts or deranged, dumb, retarded, and other similarly inflammatory languages. 

Do not correlate mental illness with violent crime. 

Review National Center on Disability and Journalism Style Guide the National Center on Disability and Journalism Style Guide if you would like more guidance on how to write about people with various forms of disability. 

Race and Ethnicity 

Only identify a person by race when it is pertinent as in biographical and announcement stories that involve significant, groundbreaking or historical events, such as being elected U.S. president, being named to the U.S. Supreme Court or other notable events. 

• Yes: Barack Obama was the first Black U.S. president. 
• Yes: Sonia Sotomayor is the first Hispanic justice of the U.S. Supreme Court. 
• Yes: Jeremy Lin is the first American-born NBA player of Chinese or Taiwanese descent. 

Capitalize nationalities, peoples, races and tribes. 

• Yes: Arnoldo Tamayo Méndez was the first Black astronaut.
• No: Arnoldo Tamayo Méndez was the first black astronaut.
• Yes: The Standing Rock protests of 2016 and 2017 were in solidarity with the Dakota and Lakota nations.
• No: The Standing Rock protests of 2016 and 2017 were in solidarity with the dakota and lakota nations.

Visit the Diversity Style Guide if you need additional guidance about how to write about people. Another great example of writing for people is the MailChimp style guide.