Content

Language is a fundamental part of the user experience. Clear and consistent interface writing helps our users get up to speed quickly and get on with their day.

Goals and tips

Be inclusive

Chorus supports a broad range of editorial teams and audiences. Ask yourself if the language you’re using applies to all of the people we’re serving.

Be consistent

Be consistent in how you describe interface elements. For instance, if you’re referring to a permalink, don’t call it a slug elsewhere. Consistency helps with onboarding, feature adoption, usability, accessibility, and reducing translation costs (if we ever decide to internationalize). Using the same name each time isn’t repetitive—it reduces cognitive load and helps people find things quickly.

Keep it conversational

When you’re writing, think about how you’d explain this issue or feature to someone in person. Imagine them sitting across from you asking, “What does this do? How does it work?” Your content should answer these questions as directly and kindly as possible. Before you publish anything, read it aloud to yourself to make sure it flows.

Usage guidelines

We follow AP style with a few key guidelines:

• Use the active voice.
• Use plain language. Avoid jargon and idioms.

Accessibility

• Be consistent with what you call things and how you spell them.
• Use descriptive links. Avoid click here and only use learn more after more descriptive text.
  • Example from feed preview: These previews are approximations and may vary by screen size or other factors. Learn more.
• Include headings to break up text into sections.
• Avoid device-oriented language. For example, select is more universal than click or tap.
• Avoid directional language (e.g., on the right side of the screen). Refer to elements as they’re labeled, not where they appear on a display.
• Avoid sighted language whenever possible (e.g., readers, viewers, see all, view all). For example, we refer to members of the public as audiences—not readers—as they may be watching videos, listening to podcasts, or using assistive technology.

Capitalization

• Use sentence case.
• Assume that what you’re building is a common noun, not a proper noun. Don’t use title case or create branded terms without consulting with the community team. For example, people can create stories, streams, and packages—not Stories, Streams, and Packages.
• Avoid using all caps for subheadings as it can impede people’s ability to differentiate between words and word shapes.

Punctuation

• Use the serial comma.
  • Example from Do not distribute tooltip: When enabled, this story will not be distributed to RSS feeds, Apple News, or other platforms.
• Use contractions.
• Avoid using ampersands.
• Use smart quotes, not primes.
• Format dates and times like so, depending on the available space:
  • Jan 17, 2019
  • Jan 17, 2019 at 3:40pm
  • January 17, 2019 at 3:40pm EDT
  • 2 days ago
  • 2 hours ago
  • 27 minutes ago

Refer to our content style guide and accessibility checklist for more details.

Components

Banners

• Check the wiki for details on banner messages.
• Don’t joke around or use words like “alert” that might up someone’s stress level.
• Don’t punctuate times and don’t mention daylight savings time (e.g., at 10pm ET).

Buttons, modals, and sidebars

• Use concise, actionable language (e.g., Publish now, Download, Save).
• Check the story editor and Chorus Video before establishing a new label or verb sequence. For example, sidebars use Close and Update instead of Done, Save, or Dismiss.

Error and warning messages

• Review existing messages before writing new ones.
• If something went wrong, explain how to fix it with a clear call to action or link for support.
  • Example warning for restricted Google Sheets in a table: Please make the Google Sheet public to continue.
• Refer to buttons, labels, and menus as they appear in the app.

Inputs and dropdowns

• Input labels should be nouns (e.g., Dek, Caption, Tags, Keyname).
• If the input’s purpose or behavior isn’t immediately clear from the label, include a tooltip to explain how it works.
• Do not repeat the label as placeholder text. Only use placeholder text if it helps people understand how to format their text.
  • Example from embeds:
    • Input label: Embed URL
    • Placeholder text: https://youtu.be/KaOC9danxNo
    • Tooltip text: Paste the link to a Tweet, Instagram, YouTube or other embed.

Tooltips

• Tooltips should outline what a feature does and what else it affects. We usually decide to add them as part of usability testing, but you can include one proactively for complex or unusual features.
• Be concise. Keep it to 15 words or less. You can save space by using this instead of repeating the name of the input or interface element.
• You can include an optional Learn more link to documentation for further reading. This does not count toward the word limit. Don’t link the entire tooltip.
  • Example tooltip for geo-restrictions: Restrict access to a video by geographic location. This only applies to Chorus player embeds. Learn more.
• Avoid using pronouns, since the person working on a story or video may not be the author of it. For example, “This story is embargoed” is preferred over “Your story is embargoed.”

Selects

• When including placeholder text, follow the pattern of the label and include an article (e.g., a, an). Don’t use Select one as a catchall.
  • Example for category:
    • Select label: Category
    • Placeholder text: Select a category

Resources

If you’re working on a new feature or message and need help with the language, reach out in Slack: #chorus-writing-lab

• Chorus Content Style Guide
• Chorus Writing Lab
• Vox Media Editorial Accessibility Guidelines
• Plain Language Action and Information Network
• Disability Language Style Guide