Content Style

We approach content as an embodiment of our vision to empower customer-centric businesses with tools that serve customers in the most helpful, human way. That means that all the content we produce, without exception, must provide real value to the community.

Content principles

We strive to elevate the field of customer service by producing high-quality, well-researched, actionable content (no surface-level, keyword-stuffed pieces that waste anyone’s time). Everything we produce — blog posts, help documentation, social media posts, webinars and classes — is the result of time, effort, and intentionality from subject matter experts with a relentless dedication to quality.

Our content strives to live up to our brand values. Above all, we want to be helpful before asking for anything in return.

Voice and tone

Our content is:

1. Thoughtful, but not verbose: Present the right amount of information in direct, confident, concise language. Take twice as long to create it so you have time to halve the word count in half.
2. Clever, but not boastful: Create content that makes people smile, or think, or understand a complex idea in simple terms — but always from a place of humility.
3. Inclusive, but not oversimplified: Use welcoming, inclusive language that steers clear of inside jokes, jargon and cultural references — but don’t shy away from complex concepts or the occasional big word. Assume our readers are smart and good at what they do; they’re coming to us to hone their skills.
4. Uplifting, but not grandiose: Help Scout is a wonderful product, but we’re not saving lives here. Use positive, uplifting language without sounding like a TV infomercial. Stay grounded.
5. Differentiated, but not disparaging: Never speak negatively of another product or approach when trying to differentiate Help Scout. Our goal is to amplify the field of customer service and conversations within it, so we exist in a cooperative space before a competitive one.
6. Fun, but not silly: We love to have fun and make people smile, but never in a way that undermines our core message. We make tools that solve real problems for growing businesses. That ability shouldn’t be called into question by creating overly silly content.

House style

Accessibility

Remain mindful about accessibility as it pertains to web content per the Web Accessibility Initiative’s Web Content Accessibility Guidelines. Use descriptive link text, for example, as well as descriptive alt text for images — what’s good for SEO is also good for accessibility.

Images

Solicit and select photos and illustrations that showcase different axes of diversity, outside the standard stock images you’d expect from the average software website.

Inclusive, gender-neutral language

For example: Use “folks” or “people” rather than “guys”; “staffed” or “handled” rather than “manned”; “go-between” rather than “middleman,” etc. Avoid ableist language (e.g., “crazy,” “OCD,” “blind,” “lame,” “insane,” and so on).

Language

We use U.S. English (as opposed to British/Australian English) by default, unless stylistically it makes sense otherwise.

Style guide

Help Scout adheres to AP style except where noted below.

Book titles

Use italics, with a link to either the book’s designated website (preferred), or a reputable bookseller.

Job titles

Capitalize all job titles (Note: “Co-founder” as opposed to “Co-Founder.”) and team/department names (e.g., “Support,” “Engineering”).

Names

Use first names in the second instance when quoting Help Scout teammates. For people outside Help Scout, use last names in the second instance.

Percentages

Use “%” as opposed to “percent” unless stylistically it makes sense otherwise.

Subheads

1. Sentence-style capitalization, not title-style (“Write them like this,” and “Not Like This”)
2. Do not end in periods
3. 60-70 characters (wherever possible)

Diversity & Inclusion

Acceptable to use an ampersand (“&”) when speaking about the concept. See also: D&I.

Lists

Use bulleted or numbered lists, never dashes. When writing a bulleted list, use periods at the end of each point when the bullet points are complete sentences. If each point is a word or short phrase, do not use periods.

Numbers

Use digits in titles and subheads even when greater than 10 (e.g., “Help Scout's 12-Step Remote Hiring Process”).

Quotations

1. Refrain from starting paragraphs with quotations; case-by-case exceptions allowed
2. Tweetable quotes should be edited for current character count limits

Support-Driven Growth

Use a hyphen to distinguish the Support-Driven Growth business approach from the Support Driven community.

Content channels

The Help Scout blog

The Help Scout Blog is geared toward founders and high-level decision makers at customer-focused companies. Our readers care deeply about the customer experience, and about growing a business their customers love.

We publish helpful, well-researched articles about company culture, customer experience, brand and design, remote work, and thoughtful approaches to business growth.

The blog also hosts Release Notes — our monthly update that highlights recent product improvements — and other product-related announcements.

HelpU

HelpU is the education resource for companies and teams who want to create better customer experiences. The content on HelpU is aimed at customer service practitioners and their leaders, and is typically practical and actionable.

HelpU aims to elevate customer service professionals, who are often under-appreciated inside organizations. It achieves this by directly advocating for them, and teaching them the skills they need to build more influence and have more impact.

HelpU content is grouped under these major topics:

1. Scaling customer service: how to grow a team, and deal with larger volumes of work
2. Support skills: practical advice for actually delivering customer service
3. Big picture: understanding the customer support market, how CS fits into business
4. Leading customer service: advice for team leaders, support directors and managers, or those looking to become managers

Individual HelpU content can be attached to playlists — collections of related content — which can include both other Help Scout content and relevant external links..

Resources

Our resources are longer-form, typically written content, targeted at both the Blog audience and the HelpU audience. They are produced in-house, but may be written in partnership with outside experts and aligned companies.

The resources are grouped into 3 sections, each customer-focused:

1. Acquisition
2. Support
3. Retention

Webinars

HelpU Webinars are educational and often practical, exploring customer service and adjacent topics in partnership with external experts. Each webinar includes a handful of practical takeaways.

Our webinars are not Help Scout-specific, but often refer to how particular actions or ideas could be implemented using Help Scout products. Our webinar partners and guests are not necessarily Help Scout users — we want to first create value through helpful, honest content and include our products where it makes sense.

Our voice and tone during webinars is consistent with our written content, although it can be more conversational and casual.

Customer communications

Support conversations

Our voice is friendly, clear, concise, and most importantly, human. Read your replies in your head or aloud before sending. Would you use those same words in a conversation with a friendly acquaintance? If not, find new words.

Adjust your tone based on the tone of the customer’s email. If they’re clearly angry, don’t be enthusiastically happy — take into account where they’re coming from. If they’re excited about something, match that excitement. Our voice should be consistent, but our tone should vary depending on the customer or situation.

Help Scout app word usage

1. Emails from customers are called conversations, not tickets.
2. Single replies within a conversation are called threads.
3. People who ask for our help are always called customers, not end-users.
4. Anyone with a Help Scout account is called a User, not an agent.
5. When referring to menus in the app, use bold and the > key. These should be capitalized. (ex. Manage > Users). Don’t use quotation marks.
6. Write file extensions in all caps: GIF, MP3, etc.
7. Always capitalize feature names. For example: Docs, Beacon, and Workflows.
8. OK: “You can use Workflows to auto-assign conversations based on various conditions.”
9. OK: “Which Workflow are you having trouble with?”

General word usage

Avoid:

1. non-inclusive language
2. “killing it,” “crushing it”
3. inconvenience
4. expressions and idioms that may not be understood cross-culturally

Be careful with:

1. unfortunately
2. sorry
3. trouble
4. issue

Common confusions:

1. login (noun) vs. log in (verb)
2. drop-down vs. dropdown
3. email (not e-mail)
4. Beacon (the product) vs. Beacons (the widgets)

Customer names

Double-check to ensure you’ve spelled people’s names correctly. Sérgio is Sérgio, not Sergio, etc. Don’t shorten someone’s name unless they have already shortened it in their email or signature. Christopher is Christopher, not Chris. Katie is Katie, not Kate, etc. If you’re unsure the “name” in Help Scout is truly a person’s name, go with something generic to avoid confusion or offense.

Gender

Don’t guess a person’s gender based on their name or avatar. If you’re unsure of the gender of the customer or another user they refer to, the singular “they” is fine. Using “he/she” or just guessing aren’t OK. Avoid gendered terms like “you guys,” “our tech guy,” and so on.

Greetings

“Hey” and other informal greetings are great for customers we know or who share our friendly, casual culture. For customers we don’t know well or whose culture we’re not familiar with, try to keep greetings more standard or match how they’ve addressed you.

1. Greetings, John!
2. Hello Amy,
3. Hi James,
4. Hey Ben,

Closings

Mailbox signatures are added automatically with every reply. Don’t sign your replies unless it’s appropriate for the type of message you’re sending.

Dates, numbers and time zones

When you’re writing a date, it’s best to type out: “November 18” or “18 November.” Using the mm/dd format can be confusing for customers who use dd/mm in their countries.

If you know what time zone a customer is in and are suggesting a time to meet, it’s nice to do the conversion on your end so that they don’t have to. If you’re not sure though, go with your own or default to Eastern Time and they can convert from there.

Write telephone numbers as 123.456.7890 or 123-456-7890. If a country code is included, add it at the beginning with a “+” — e.g., +1 123-456-7890.

Status site communication

Keep messages short, simple, and clear. Don’t provide unnecessary technical details — customers want to know we have our eye on an issue, not the technical guts of the problem. For customers who are curious about the more technical side, engineering provides public post-mortem for any major status event.

For the first 30 minutes of a status event, post an update when you actually have new information. If the status event lasts longer than 30 minutes, make sure status is updated once every 30 minutes. Only send email notifications for the first post and the final post.

Things to keep in mind

1. Clarity and humanity (your own and the recipient’s) above all else.
2. Be accessible. Short words > long words. Use lists. Avoid jargon.
3. Metaphors and similes can be helpful in explaining technical concepts. If they themselves become complex, they’re not helpful any longer, and should be scrapped.
4. Don’t be too didactic — minimize words like “ought to” and “should” when talking about the customer and their team.
5. Use bold or italics to emphasize — never all caps.
6. The goals of a support reply are to answer the person’s question and to make them feel heard. You might be able to answer a question with a link to a Docs article, but framing that within a sentence or two is more human.
7. Remember your audience. Would someone with little knowledge about Help Scout understand what you’ve written?
8. Contractions, exclamation points, emoticons, emoji, and gifs are great ways to convey meaning with humanity. Remember to modulate your tone for the situation.
9. If you don’t understand something well enough to explain it clearly, ask a teammate for help understanding it.

Help documentation

Before writing a new Docs article, consider:

Why are you writing the article?

Defining the “why” before drafting the “how” helps identify puzzle pieces, and where they need to go when you start writing.

What is the purpose of the article?

Think about what you want the reader to accomplish.

Who is reading the article?

Is the article meant for Users, Administrators, or both? Is the article for a new, potential customer or a seasoned User?

What does the article look like?

Preview the article frequently as you write. Pay attention to formatting, paragraph structure, image placement, and overall length of the article.

Article structure

Complex topics can require long explanations, but sometimes more specific content is more helpful. Break out long articles that cover multiple, related topics, in to separate articles when appropriate. On the flip side, long-form content is helpful for things like Getting Started guides and knowledge clusters, where lots of relevant content is packed in to one article.

Creating a scannable, neatly organized article is essential to keeping readers on task. Each Docs article contains the same content structure:

1. Title
2. Introduction
3. Table of contents
4. Body content

Titles

Create simple, specific article titles. Readers should have a clear idea of what questions are answered in the article.

1. Use title case, except for conjunctions and prepositions. “Price and Plans Guide” not “Price and plans guide”
2. Capitalize the names of Help Scout-specific features. “Workflows, Beacon, Docs”
3. Capitalize the names of third-party applications.
4. Avoid nouns, verbs, and adjectives ending in -ing. “Manage Account Security” not “Managing Account Security”
5. Titles are always simple statements, never questions. “Edit Customer Profiles” not “How do I edit customer profiles?”

Introductions

Article introductions let the reader know what the article contains, or what questions the article answers. Avoid sales pitches and funny catchphrases. If a feature is plan-specific, the introduction is a great place to mention which plan a feature is available on.

Table of contents

A table of contents provides the reader a quick way to find what they’re looking for. Create a table of contents for articles with two or more key points. Link each list item to its corresponding Header 3 text.

1. Use Heading 4 for the In this article title text.
2. List article sections using an unordered (bulleted) list.
3. Add anchor links to each bullet point.
4. Use this HTML to style the table of contents:

<section class="index-list"></section>

Body content

Stay relevant, clear, and concise. Use as few sentences in a paragraph as possible, and try to avoid big words and long sentences. Use active voice, not passive voice. Add context using images to make content easier to understand. Always use an Oxford comma when making lists.

Headings and sub-headings (H3, H4)

Additional headings help break up ideas and important concepts. Headings and sub-headings can be a little longer and more specific than article titles.

1. Use Header 3 for primary section titles. Use Header 4 for sub-headings under Header 3.
2. Headings and sub-headings also use title capitalization. “Write Them Like This” and “Not like this.”

Step-based instructions

Definition lists are great for step-by-step instructions. Use definition lists when the primary purpose of the article is to explain how to complete a task in the app.

1. Steps should be in sentence and paragraph format.
2. Keep definition lists to nine or fewer steps when possible.

Callouts

Callouts are small, styled text boxes that are ideal for calling attention to important reminders that you want the reader to remember. There are multiple callout colors available, but we only use yellow callouts within Docs articles.

<section class="callout-yellow">
  <h3>This is a yellow callout</h3>
  <p>Just add class="callout-yellow". It's really that easy.</p>
</section>

Images

Clearly cropped images help the reader get their bearings in the app. Use images sparingly, but don’t shy away from adding an image if it’s helpful.

1. Crop images neatly and proportionally.
2. Avoid large margins or areas of white space.
3. If you’re capturing images on a Retina display, scale down the image (size equally to 50%) before saving.
4. Avoid all annotations, such as arrows, shapes, and text.
5. Use the browser console to edit HTML on the page to make image content consistent. For example, images showing how to edit a User profile should show the same User name in each image.
6. Images are always aligned to the left, with no text wrap.
7. Save images as .JPEG or .PNG, make them a reasonably high quality.
8. Use an image optimization tool, such as ImageOptim to optimize images before uploading.

Lists and bulleted lists

Ordered (numbered) lists can be used to explain a series of steps or reminders that don’t require multiple actions or related images. Unordered (bulleted) lists are helpful for grouping together concepts or ideas.

Bold text

Bold text is reserved for highlighting specific call-to-action items. When writing descriptive text, use bold text to highlight the name of a menu item, link, or button: “Click the Notifications link. Select your desired notifications, then click Save Notifications.”

Contact Us

To call out a contact us in an article, use the link to the contact modal rather than a mailto: link with our email address. The a tag for this is:

<a href=''#contactModal' data-toggle='modal' class='contactUs'>

Article slugs

Article slugs are part of the article URL. The article slug should match the article title, word for word.

Title: Manage Voice Messages

Slug: article/71-manage-voice-messages

Proofread

Proof your article before publishing. Read it again, again, and again. Before publishing the final version, ask a teammate to read the article. Check for spelling, grammar and punctuation errors. Run the content through a service like Grammarly or Hemingway as an extra proofreading step. Clean up extra HTML tags or spacing in the HTML editor.