NYC web content style guide

Foundations

About this guide

This is a guide to writing content for official NYC government websites. By following these guidelines, writers will help make NYC government content easy to understand, accessible, trustworthy, and consistent.

This guide is one part of the NYC Digital Design System, which also includes visual design and engineering guidelines.

Follow these guidelines whenever you write for nyc.gov. You should also follow them when you write for any other public-facing NYC government websites or applications. 

Why should I follow these guidelines?

If your website is supported by the Office of Technology and Innovation (OTI), you’re required to follow these guidelines. 

These guidelines also align with Local Law 30 of 2017 [PDF] to facilitate effective language access. Among other things, the law requires covered agencies to use plain language for “documents most commonly distributed to the public that contain or elicit important and necessary information regarding the provision of basic city services and for other public communications.”

Most importantly, following these guidelines helps New Yorkers.

How should I use it?

We recommend reading this guide all the way through. Then, bookmark this page for quick reference while you’re writing content. Use the jump links to navigate to specific sections. 

You can also download and print a poster featuring the most important guidance.

Download tabloid size poster [PDF]

Download letter size poster [PDF]

Web version of poster

Acknowledgments

This guide is based in part on the 18F Content Guide by 18F, the former digital service team within the federal General Services Administration. Plain language guidance is based on the federal plain language guidelines. We referenced the AP Stylebook, 57th Edition for style rules.

Feedback

We encourage NYC government employees to contact us with questions or feedback.

Contact us

Rights

This guide is an open-source document. Feel free to copy, change, and reproduce this guide to suit the needs of your organization.

Content principles

As government writers, we have a responsibility to our users. It’s on us to do the hard work to make content better. Users shouldn’t have to work hard to find, read, or understand our content.

By following these five principles, we can write content that works better for New Yorkers. 

For users, not for government

• Always start with real user needs

• Write action-oriented content that helps users get things done

• Never include information that only government users care about

• Structure content by how users actually think about a topic

Easy to understand

• Use plain language and simple sentences

• Prioritize clarity over sharing every detail

• Put content where users expect to find it

Accessible

• Meet WCAG 2.2 accessibility standards so the content is accessible to users with disabilities

• Write as simply as possible without losing meaning

• Write content that is easily translated into non-English languages

• Make sure content is readable on mobile devices

• Use web-based content instead of PDFs or images containing text

Trustworthy

• Update content often

• Make sure information is accurate

• Use natural language instead of jargon

Consistent

• Follow the web content style guide

• Use similar structure and layouts for similar pages

• Don’t call the same thing by many different names

Plain language

All public-facing content on nyc.gov should be written in plain language. Plain language means your audience should understand your writing the first time they read or hear it. 

The most common techniques for writing in plain language are:

• Use simple, everyday language

• Avoid jargon

• Use "you" to speak directly to the user 

• Use active voice 

• Use the simplest tense possible (usually present tense) 

• Use as few words as possible 

• Avoid idioms and turns of phrase

• Use short sections

• Use short sentences 

• Present each topic or point separately  

• Order content in a logical, intuitive way

• Use descriptive headings

• Use lists and tables to simplify complex content

• Use links that describe what the user will get when they click

Plain language techniques are described in depth at plainlanguage.gov. Take some time to read the detailed guidance and examples on that site.

Reading level

Always make your content as simple as you can without losing meaning. Try to simplify your content to a seventh grade reading level or lower. 

We use the Flesch–Kincaid grade level formula. You can use Microsoft Word, Hemingway, or another tool to check Flesch–Kincaid grade level. While this formula isn’t perfect, it’s good enough to flag passages that should be simplified.

There will be times when you can’t achieve a seventh grade reading level. In these cases, try to reduce the grade level as much as possible using plain language techniques. Frame more complex passages with simple sentences to help users find the information they need.

Voice

Our voice is:

• Authoritative: We sound credible and well-informed. Users can rely on our content to be accurate and trustworthy. 

• Clear: We speak directly to our users’ needs with concise, task-oriented content that’s easy to understand.

• Human: We sound helpful, friendly, and empathetic. Our language is natural and conversational.

• Inclusive: We speak to everyone. Our content empowers people by using language that makes them feel seen and respected.

Our voice is not:

• Didactic: Our content serves to inform and guide. We don’t sound morally superior or patronizing.

• Cold: We avoid overly formal or impersonal language that could come across as robotic or bureaucratic.

• Nonchalant: We take our users seriously and don’t use jokes, idioms, or trendy language that could be alienating.

• Opinionated: We deal in facts and don’t take sides on issues without clear evidence.

Generative artificial intelligence (AI) tools

Generative AI tools can be helpful for writing and editing content. 

In general, it’s OK to use generative AI tools for writing and editing content as long as:

• The software has been approved for use by the Office of Technology and Innovation (OTI).

• The content you’re working on is public-facing and does not contain sensitive or restricted information

Note that there are specific policies governing the use of AI in city government. You can find more information on the OTI website. 

Be careful when using generative AI tools. Generative AI often writes misleading or inaccurate content. It’s important that you have a human editor review any AI-generated content before publishing it online.

AI-generated content should be checked for:

• Accuracy

• Missing information

• Use of plain language

• Seventh grade reading level

• Compliance with the style rules in this guide

You should also disclose the use of generative AI to your audience. If you’re writing content for nyc.gov, the about our content page linked in the footer discusses the use of generative AI for editing.

Style rules

Follow these rules for all public-facing web content. If a rule isn’t explicitly covered in this guide, use AP style.

Abbreviations

In general, avoid abbreviations that shorten or truncate terms (such as appt or gov’t).

Exceptions:

• When the abbreviation is more common than the longer term (such as email for electronic mail)

• St., Ave., Pl., and other street suffixes in addresses

• Info is acceptable as a shortening of information

• ID is acceptable as a shortening of identification

See also: Acronyms

Write all buttons in sentence case. Be sure to follow all other capitalization rules. Don’t include punctuation.

Contractions

Use contractions (such as can’t, don’t, and they’re). 

Contractions make writing friendlier and increase readability. You don’t need to use them in all cases, just wherever they sound natural.

Capitalization

Be careful with capitalization. Government writing is often over-capitalized, which can imply formality where it doesn't exist. Capitalization is not a signal of respect or rank. It's simply a way to help readers understand content.

If you have a specific question about whether something should be capitalized, refer to AP style rules. 

General rules:

• Capitalize proper nouns, including names of individuals, places, agencies, programs, and official documents.

• Capitalize the first letters of sentences and list items.

• Write headings, buttons, and links in sentence case (not title case).

• Only use all capital letters for acronyms or stylized brand names. Never use all caps for emphasis. 

Don’t capitalize:

• Titles or offices unless they come immediately before a name: President Abraham Lincoln. The president visited New York. 

• city or government in contexts like city government, city officials, government agencies

• Web domains: nyc.gov, usa.gov

• The names of products or applications, unless they are a brand name

• The word program if it is not part of the official program name: Free Summer Meals program

See also: Headings, Names and titles, Specific words and phrases

Emojis

Don’t use emojis.

Frequently asked questions

Frequently asked questions (FAQ) can be a useful way to organize dense information. But they can also be frustrating for users to navigate. 

To write better FAQ, follow these guidelines:

• Don’t bury the most important information in FAQ. 

• Reserve FAQ for information that only applies to some users. 

• Write questions that users are really asking. 

• Don’t repeat information from other pages inside FAQ. Link to those pages in the main content instead.

• Include seven or fewer FAQ per page.

• Favor writing out frequently asked questions rather than FAQ. If you must use the term FAQ, treat it like any other acronym.

Heading styles are used to communicate the content hierarchy. We use heading styles H1, H2, H3, and H4 on nyc.gov. 

• H1 is used for the title or primary headline of the page. There is usually only one H1 per page.

• H2s are used for section headers. 

• H3s and H4s are used to break up content beneath H2s. 

• Heading styles should always nest in order from largest to smallest (H1, H2, H3, H4) and should not be skipped.

Inclusive language

Inclusive language helps us build trust with our users. In general, write in a welcoming tone and avoid language that alienates specific groups of people.

Ability and disability

The Mayor’s Office for People with Disabilities (MOPD) publishes a disability-inclusive terminology guide with specific words and phrases to use and avoid. 

Age 

The term older adult is more inclusive than senior, senior citizen, or elderly.

Criminal justice

Avoid terms that define people based on their interactions with the criminal justice system. For example:

• Use incarcerated person or person in custody instead of inmate or prisoner.

• Use person convicted of a crime instead of convict or criminal.

For more detailed guidance, see the National Institute of Justice Style Guide.

Gender and sexuality 

Make content gender-neutral wherever possible. 

Specific guidelines:

• If you don’t know a person’s pronouns, use they, them, and their (never he/she, he or she).

• When speaking generally, use spouse or partner instead of husband or wife.

• When speaking generally, use parent instead of mother or father.

• Use different sex instead of opposite sex.

For more detailed guidance, see the GLAAD Media Reference Guide.

Nationality and immigration

Avoid using citizen as a generic term. New York City is home to many non-citizens and people with a wide range of immigration and visa statuses.

• Use resident or New Yorker instead of citizen.

• Use older adult instead of senior citizen.

• When discussing immigration status, use undocumented immigrant instead of illegal immigrant.

Race, ethnicity, and religion 

Avoid using language that reinforces racial, ethnic, or religious stereotypes.

Avoid the term non-white and other terms that treat whiteness as a default.

When referring to a person’s race or ethnicity, use adjectives, not nouns (for example, an Asian person, not an Asian).

Media style guides for race, ethnicity, and religion:

• National Association of Black Journalists Style Guide

• Guidance from the Asian American Journalists Association

• Native American Journalists Association Reporter's Indigenous Terminology Guide [PDF]

• Religion Newswriters Association's Religion Stylebook

Set links to open in the same tab or window. Links should not be set to open in a new tab or window except in very specific circumstances. 

W3C: Opening new tabs or windows

See also: Organization names

See also: Dates and times

See also: Names and titles

Phone numbers

Write phone numbers in this format: (212) 639-9675

For numbers that include words, use this format: 212-NEW-YORK (212-639-9675)

Prepositions

It’s fine to end a sentence with a preposition.

Text alternatives

Text alternatives help blind and low vision users understand the meaning of images. 

To meet accessibility standards, most images used on the web must have an appropriate text alternative. Images that are purely decorative must be hidden from screen reader users.

This guide from W3C provides information on when to use text alternatives and how to write them.

Italics

Don’t use italic text in web copy.

Strikethrough

Don’t use strikethrough text in web copy.

Underline

Don’t use underlines for emphasis. In web copy, underlines always indicate a link.

URL paths are case sensitive. If for some reason you’re writing out a full URL (including a domain and a path), check to make sure the path is correctly capitalized. 

See also: Meta titles and descriptions