Content style guide (A to Z)

If you are writing for SF.gov, use the following grammar and usage, based on AP Style. If something is not listed below, use AP Style.

Use Ctrl + F to search within this page

Acronyms

Acronyms help people who know your content, but are difficult for first-time users to understand. Also, because your pages will be on SF.gov with many other departments, acronyms may have different meanings in different contexts. For example, "ADU" means "Accessory Dwelling Unit" to the Planning Department, but to the Department of Public Health, ADU means "addictive diseases unit".

Write out acronyms the first time you use them on a page, including the acronym in parentheses. Do not use periods in any acronyms.

You can then use the acronym further down the page.

The Mayor’s Office of Housing and Community Development (MOHCD)...

...MOHCD will...

If you need to use the acronym to keep your title short, you must spell it out in the description.

Contact the City about your ADU

City planners can answer early questions about accessory dwelling unit (ADU) options and requirements.

Where the acronym is better known than the full term, do not write out the term. For example:

  • IRS

  • USA

  • ATM

  • PIN

  • URL

  • USPS

  • PDF


&, and

Use 'and' rather than & unless the '&' is part of the name, like Treasurer & Tax Collector.

Why: In some instances '&' can be corrupted to display as '&'. Also, you are calling attention to the least important word in the sentence.


Bullets

Bulleted lists make content easier to read, but only if the bullets are short. Bullets should always follow a lead sentence. The lead sentence ends with a colon. Bullets should start with a capital letter and have no punctuation within the bullet points.

Most people’s working memory can only take in 3 to 5 things. So work with people’s brains and use 3 to 5 bullets. Long lists are difficult to read and remember.

Do

You must submit:

  • A copy of your driver's license

  • Your social security number

  • A photo


I like to eat:

  • Apples

  • Bananas

  • Pears

Don’t Do

Things you will need to do for your application:

  • You must show a photo id like your driver’s license. You will also need proof of your social security number.

  • Go to counter 30 and ask for Susan. She only works on Tuesdays and Thursdays. You should call to make sure she is in


  • On Tuesdays talk to Susan

  • On Wednesdays talk to John

  • On Fridays talk to Mary


Buttons

Buttons can be up to 25 characters. The shorter the button text, the more effective it is!

Always start with a verb, like “Apply” or “Get”

See our button text library for examples.


Capital letters (caps), ALL CAPS

Capital letters are harder for our eyes to read, and slow readers down. That’s helpful for highlighting names, acronyms and places, but not for highlighting headings and text. On SF.gov, our style is to use capital letters infrequently.

We do not write in all caps on SF.gov. People with dyslexia have trouble comprehending the words, and it’s more strenuous for everyone to read.

ON THE INTERNET, ALL CAPS IS HOW WE NOTE SHOUTING, RATHER THAN COMMUNICATING.

 

Mayor London Breed

Closed on public holidays.


Add emphasis with white space, using paragraphs and bullets.

MAYOR LONDON BREED

Our office is closed ON ALL PUBLIC HOLIDAYS.


Distract readers by highlighting too many things, drawing focus.


City

Always capitalize 'City' when it’s short for the City and County of San Francisco or when used in place of San Francisco.

Search for jobs with the City

We want to significantly reduce the City workforce's carbon footprint.

If you are talking about cities in general, don’t capitalize.

Many cities have passed sanctuary ordinances.

Climate change is a big concern for cities across the United States.


Comma, serial or Oxford

If you have a long sentence, try to replace commas with periods.

In a series, use a comma after all items (Oxford comma).

I like to eat apples, bananas, and pears.

I like to eat fruit salad, eggs and bacon, and hash browns.


Contractions

Shortening 2 words into 1 can make your writing more informal and friendly. However, negative contractions, like 'don’t' and 'shouldn’t' are sometimes misread, particularly in instructions. So on SF.gov, do not use contractions in service or instructional content.

For a news story or lighter content, it’s fine to use contractions.


Dashes and hyphens

We do not use dashes on SF.gov.

If you have used a dash, try to rewrite the phrase or sentence.

We use hyphens in common nouns, phone numbers, and zip codes.

Use a hyphen (-) without spaces on either side to link words into a single phrase. When the phrase can be spelled as one word, remove the hyphen.

Do not use a hyphen to indicate a span or range, instead spell out the range.

building with 203 units

meeting

Monday to Friday

isolate yourself at home

cosponsor

in-law unit

car-free

10-minute delay

800-708-6733

94102-9911

203-unit building

in-person meeting

Monday-Friday

self-isolate at home

co-sponsor

 


Dates

We write dates as month, day, year. We write out the month and use numbers for day and year. We write years as 4 numbers, like 1900 and 2020. It’s best practice to include the year, but not mandatory.

Other countries use different formats for dates, so it’s clearer to write out the month. And some people find it difficult to read '/'.

When writing dates use cardinal numbers, not ordinal. When speaking about dates the convention is to use ordinal numbers, but in writing, the convention is to use cardinal.

When space is limited use only the first 3 letters of the month. Otherwise, write out the month.

January 28, 2020

Jan 28, 2020

Tuesday, January 28, 2020

1/28/2020

1/28/20

Jan 28

January 28th

See Years for calendar years, tax years and school years.


Ellipses

Do not use ellipses. They cause confusion.


Gender

Do not ask for gender unless you really need it. Making people fit themselves into categories can stress people.

Also, there is a risk to storing and managing that data securely. Make sure you have a plan to store and anonymize the data, and that the value of the data is worth the risk.

If you do really need it, explain why you need it and how you will use the data. Tell people how you will store the data safely.

We talk about 'transgender and gender nonconforming people'. If you are writing for experts, you can use 'gender nonconforming (GNC)' when you use the term first. Then you can use GNC after that.

Male
Female
Trans male
Trans female
Genderqueer / Gender Non-binary
Other _______
Decline to answer

This format allows people to choose if they want to disclose if they are transgender or not, as they could also just select the Male or Female options.

For new staff, only ask demographic questions after hiring, such as during an onboarding survey, so there is no potential discrimination in the hiring process.


In order to

Do not use “in order to” when you mean “to”. It may seem more precise or formal but it does not add to understanding.

The Domestic Partnership must be filed with the County Clerk to have a commitment ceremony performed by our office

The Domestic Partnership must be filed with the County Clerk in order to have a commitment ceremony performed by our office.


It is, it’s and its’

It's = it is (or it has)

Its = belonging to it

Its’ = no meaning. Don’t use.

It’s a short drive to Mountain View.

The monster is green. Its teeth are yellow.


Latin

Do not use i.e., e.g., or etc.

Because they are Latin terms, they are not easily understood by everyone. Because of the periods, these terms take visual prominence in your sentence. They shouldn’t.

Screen readers also pronounce these terms unpredictably.

Like

Like, for example (or leave it out)

Don’t use; be specific or don’t include the term

i.e.

e.g.

etc.


Links

Link to webpages, not pdfs. We do this so links don’t get broken if the webpage owner updates the PDF.

Also, let the webpage owner know if you have used information from their page, like fees, that will need to be updated.


Link text

The link text should tell people where they will go if they click the link.

Don't use 'here' as a link, ever. People who use computers to read the screen for them frequently set their machines to start a page by reading out the links. Imagine how frustrating it is to hear 'click here', 'here', 'see here'. And everyone skims links on a page, as they are blue and underlined.

If you need a birth certificate for a child under 3 years old, go to the Department of Public Health Office of Vital Records.

Check the full list of who needs to register.

If you need a birth certificate for a child under 3 years old, click here.

Click here to see who needs to apply.


Nonprofit

Do not use non-profit or not-for-profit. This is from the AP Style.


Numbered lists

Numbered lists show steps that are done in order. You can use more than one sentence in a numbered list item. Put periods at the end of each item. You do not need a lead in sentence for a numbered list.


Apply for a spaceship permit

  1. You must show a photo ID like your driver’s license. You will also need proof of your social security number.

  2. Get 3 copies of your spaceship plans.

  3. Go to counter 30 to fill out an application.

I like to eat:

  1. Apples

  2. Bananas

  3. Pears


Numbers

Always use numbers, even for 1 to 9. Numbers are much faster and easier to read.

Write out numbers at the start of a sentence, or in the expression "one or two". Also write out numbers if it might cause confusions, like "7 two-bedroom apartments."

Spell out 0 when it is the only used number.

There are zero confirmed cases of novel coronavirus in San Francisco residents.


Phone numbers

Format phone numbers 415-555-1212.

This format works with the largest number of browsers.


Placeholder

Don’t use placeholder text, also sometimes called hint text or ghost text.

  • It can’t be automatically translated

  • When used in place of a label, it locks out assistive technology

  • It can negatively affect a user’s ability to recall information

  • It can be too light-colored to be legible

  • It may look like pre-filled information and users might accidentally neglect to input what’s needed

Instead of placeholder text try this:

  • Add placeholder content above the input, but below the label

  • Write labels that clearly and succinctly describe the input’s purpose


Please

Don’t use "please" when you are telling San Franciscans what they need to do. Be direct and authoritative.


Time

We use a 12-hour clock, followed by lower case am or pm. We do not include minutes unless needed. But, if minutes are needed, they should be used in all times in the section.

Write out 'noon' or 'midnight'. If you’re giving hours you are open, we use the phrase 'We are closed on public holidays'.

11 am to noon

Monday, 7:30 am to 5:00 pm

Tuesday, 9 am to 5 pm

Wednesday, 4 to 5 pm


United States

Use US and not U.S.


Welcome to…

Don’t "welcome" the reader to your content. San Franciscans are on the page to get something done. Get right to it.


Years

Years are always 'month year to month year'. Where space is an issue, abbreviate the month to 3 letters. Do not use 'school year' or any other type of year, as they are not commonly understood across departments.

January to December 2020

September 2019 to August 2020

Tax year

19/20 School year

 

We do not use 'year-year' because it’s unclear. Many departments use different 'years', like a school year, a tax year or a calendar year. Even a school year can be September to May or August to July.