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.
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.
Do
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
Don’t Do
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.
Do
January 28, 2020
Jan 28, 2020
Tuesday, January 28, 2020
Don’t Do
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.
Do
The Domestic Partnership must be filed with the County Clerk to have a commitment ceremony performed by our office
Don’t Do
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.
Do
Like
Like, for example (or leave it out)
Don’t use; be specific or don’t include the term
Don’t Do
i.e.
e.g.
etc.
Links
If you put https:// or www. in front of a text string, the text will become a link when you publish.
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.
Do
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.
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.
Do
Apply for a spaceship permit
You must show a photo ID like your driver’s license. You will also need proof of your social security number.
Get 3 copies of your spaceship plans.
Go to counter 30 to fill out an application.
Don’t Do
I like to eat:
Apples
Bananas
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.
Do
January to December 2020
September 2019 to August 2020
Don’t Do
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.