SlideShare a Scribd company logo

Salesforce voice-and-tone

•
•
CMR WORLD TECH
CMR WORLD TECH

This document provides guidelines for writing content for Salesforce using the appropriate voice and tone. It discusses how voice reflects personality while tone reflects mood or feeling. The guidelines recommend writing in an honest, clear, fun, and inspiring voice. Tone should be adjusted based on the audience, such as being encouraging for admins but direct for developers. The document provides tips for writing concisely, conversationally, directly, and positively. It also discusses using humor judiciously and avoiding cultural references. Examples are given to illustrate how to apply different tones for various audiences and scenarios.

Related slideshows

Business Writing
Business WritingBusiness Writing
Business Writing
 
Submit individual sections development exercise # 2
Submit individual sections development exercise # 2Submit individual sections development exercise # 2
Submit individual sections development exercise # 2
 
Effective Business Writing
Effective Business WritingEffective Business Writing
Effective Business Writing
 
1 of 14
Download to read offline
Salesforce Product & Content  VOICE & TONE Guidelines  INTRODUCTION  OUR   VOICE  WRITING   GUIDELINES  OTHER   RESOURCES  VOICE   &   TONE   EXAMPLES      INTRODUCTION     Why do we need voice and tone guidelines?  To connect with our customers, we need to talk in a way that resonates with them. The right voice  makes people feel at home through content that speaks their language.      How is voice different from tone?    ● Voice reflects our personality. It’s what we say.  ● Tone is the way we speak. It’s how we say things.    Our voice stays consistent across all of our content. Tone expresses the mood or feeling—which  should change based on your audience and the situation.      OUR VOICE, TONE, & AUDIENCE   When writing for Salesforce, our voice is always:   ● Honest: Trust is our #1 value, and we’re truthful in our writing.  ● Clear: Our writing is concise and easy to understand.  ● Fun: We’re dedicated to conversational, upbeat language.  ● Inspiring: We help people live their best lives, and our writing harnesses that genuine emotion.  p. 1 
Take a look at our Corporate Voice and Tone to learn more about our company values.  Adapting your tone  Again, while our voice (our personality) doesn't change, we adjust our tone based on the audience.  For example…  ● Admins like encouragement and the occasional "You did it! Good job." ● Developers, not so much. They'd prefer we just get to the point, and they like it when we're honest about “gotchas.” ● New end users can be intimidated by all that’s in Salesforce. They need approachable, step-by-step introductions to terms and concepts. ● Salespeople don’t have time for lots of text. They need to get in, find what they need—and get right back to closing those deals!. See our voice & tone examples to see where these different tones are appropriate.  WRITING GUIDELINES  Part of what makes Salesforce documentation special is the way we talk to the reader. It  doesn't sound like enterprise software documentation. It sounds more like a conversation  with your buddy. With that in mind, here are some tips for writing “the Salesforce Way.”  Be concise.  ● Use as few words as possible. Avoid unnecessary and redundant information. ● Focus on user goals; make sure that you create content for an actual use case. ● Avoid large blocks of text. Avoid long, complex sentences. Be conversational.  ● Use natural, conversational language with a friendly, upbeat tone. ● Contractions are OK. ● Write from the users' perspective to help them accomplish tasks. ● Avoid developer-focused terminology, unless you’re writing for a developer. Be direct.  ● Use plain English. Avoid buzzwords, jargon, and words you wouldn't say in person. ● Use active voice, and avoid complex verb structures. ● Refer to user-interface elements by their literal names, not variations thereof (e.g., “click Submit” vs. “then save it”). Be positive.  ● Whenever possible, phrase sentences positively, not negatively. Negative: The mini view doesn't appear if the record in the detail view doesn't have any records associated with it. Positive: The mini view appears when the record in the detail view has associated records. p. 2
● When describing feature improvements, focus on new benefits to users, rather than on the  design problems they addressed.   Example: We’ve made important improvements to the side panel that increase your users’  productivity.    Be clever. But don’t try too hard to be funny.  ● Have fun—it’s part of our brand! But use humor judiciously, and know your limits. (Not everyone’s  a natural comedian.)  ● Focus on clear, concise content over clever language. Make sure content is understandable  independent of any witticisms.  ● If you do use jokes, keep them “family-friendly” and inclusive. (For instance, don’t make jokes  about dads unless you make jokes about moms, too.)    Give information “just-in-time.”  ● Introduce required conceptual information only when the user is performing the related task.    ● Explain business rules or constraints only when the user encounters their constraining effects.    Watch out for cultural references.  ● Be careful with allusions or culturally-specific language that may be lost on a diverse audience.    ● If you use any idioms in the UI, clarify them in a code comment for the localization team.    Use please sparingly.  ● Use please only when asking the user to do something inconvenient or when the system is to  blame.   Example: The export process may take a while. Please wait until the process completes.    Avoid sorry.  ● Use sorry only in error messages that result in serious problems for the user (for example, data  loss, the user can’t continue to use Salesforce, or the user must contact Support).   Avoid: Sorry, but you must supply a search string of at least two characters.  Better: Sorry, but you must exit and log in again.  ● Before you use sorry in UI text, ask yourself if we could change the design to avoid the situation.    Use exclamation points sparingly.  ● Use exclamation points to be encouraging or generate excitement.   Example: Almost there! [To show progress during a process.]  ● Don’t use exclamation points in error messages, confirmation messages, or instructional text.  Avoid: Your changes were saved!     Design text for easy scanning.  ● Users often scan rather than read, so put the important points first.   Put actions before explanations.    ● Use short bulleted lists.    ● Assume that after users have figured out what they need to do, they immediately stop reading  and do it.   ● Use See Also links at the end of topics to refer users to additional, related information.  p. 3 
Provide clear instructions for users to correct errors.  ● For error messages, give the user clear instructions on how to correct the error. Example: This Self-Service username already exists. Choose a unique Self-Service username. ● Avoid phrasing that blames the user or implies user error. Passive voice can be appropriate in messages to achieve this purpose. Avoid referring to the location of items on a page.  ● Don’t use below, following, above, or other directional words to refer to the location of elements on a page. ● Exception: In walkthroughs, and in error message where a user has clearly missed a button or control, directional instructions can be helpful for many users. OTHERRESOURCES  Trailhead: Writing Style badge (get it!)  UX: Lightning Design System   p. 4
VOICE & TONE EXAMPLES  These examples help you apply the voice and tone guidelines for different audiences and scenarios.  EXAMPLE 1: Salesforce1 App (Phone)  Navigation menu callout (top left)  Search callout (top right)  ABOUT THIS EXAMPLE  Audience: First-time Saleforce1 Mobile app users  Goal & tone: The goal is to let users know what the navigation menu and search icons do, and  generate enthusiasm for using the app. Since it’s a mobile app, the text is minimal, and the tone  is friendly and conversational: “Here’s your stuff!”  p. 5
EXAMPLE 2: App Quick Start    ABOUT THIS EXAMPLE  Audience: New Salesforce admins  Goal & tone: The goal is to help new admins get started quickly. We want their first experiences with  Salesforce administration to be successful and productive.   “Tell us about your app, and we’ll whip up the basic parts for you.”  The tone is conversational and human (“us” and “we’ll”). We want them to know we’re here to help:  just give us some info, and—voila!—we’ll give you an app.   “You can always change this and other labels later.”  “You can add more later.”  The text is reassuring: by telling users they can go back and make changes, we show that we  understand their fears as new users, and let them know they’re not doing anything they can’t fix later.      EXAMPLE 3: Widgets Message Block      ABOUT THIS EXAMPLE  p. 6 
Audience: Admins  Goal & tone: The goal is to quickly communicate what widgets do and their benefit for admins. The  tone is direct and conversational, but not overly chatty.       EXAMPLE 4: Walkthrough (CRM Free Trial, Initial Tour for Sales Reps)      Accounts, Contacts, and Leads Tabs    Opportunities Tab    Reports and Dashboards Tabs    Setup Link    Walkthrough Side Panel    Import Contacts Widget      ABOUT THIS EXAMPLE  Audience: Sales reps evaluating Salesforce  Goal & tone: The goal of this walkthrough is to drive purchase and/or adoption of Salesforce. We  want our customers to know that we get them: Sales reps are busy and driven, so the tone is  direct and clear rather than chatty, and uses the same words they do. It also empathizes with  their pain points: a messy desk and a busy schedule. It also acknowledges what’s important to  reps: identifying and closing deals, hitting quota.   p. 7 
Notice how we’ve used the same tone in both heading and text, and that we end with a call to  action: “Import your contacts now!”      EXAMPLE 5: Release Notes (Communities)    ABOUT THIS EXAMPLE  Audience: Admins  Goal & tone: The goal of this section is to let admins know that they have more flexibility and  control over their community page layouts. It’s focused on what admins can do now. The tone is  energetic, positive, and user-centric: “Looking for more granular control…?” “that’s exactly what you  get!”  The section goes on to describe the various layouts (text omitted), concluding with some concrete  examples to help admins get their heads around it: “Let’s say you create three pages for your  upcoming Spring campaign....”     EXAMPLE 6: Quick Start Developer Text      ABOUT THIS EXAMPLE  Audience: Developers  p. 8 
Goal & tone: The goal of this developer guide is to encourage developers to create their own apps  for the Salesforce1 mobile app. Here’s a topic that sets the right tone. Brief, to the point, and  acknowledges the fact that readers (developers) would rather not be reading.      EXAMPLE 7: Lightning Experience Chatter Publisher      ABOUT THIS EXAMPLE  Audience: Chatter users  Goal & tone: The goal of the ghost text is to tell users what kind of information they can enter in a  Chatter post, and the ellipsis invites users to tell readers about their situation.      EXAMPLE 8: Salesforce Mobile SDK Guide    ABOUT THIS EXAMPLE  Audience: Developers  Goal & tone: The goal of this developer guide is to encourage developers to create their own apps  for the Salesforce1 mobile app. The tone is light, friendly, conversational. It starts a sentence with  "But" instead of "However." It takes on an empathetic, reassuring tone with the phrases, “don’t worry,”  and “you should be able to follow along just fine.” It uses casual, everyday language, “admin,” instead  of “administrator.”      p. 9 
EXAMPLE 9: Getting Started with Apex Trailhead Module    ABOUT THIS EXAMPLE  Audience: Developers  Goal & tone: The goal of this Trailhead module is to introduce developers to Apex. The  conversational and relaxed tone makes readers feel comfortable trying out a new programming  language. For example, it reassures readers that we’re in this together by starting the module with  “Let’s.” The phrase “on the fly” and the adjective “handy” reinforce the friendly tone—it’s like the  programmer sitting next to you is helping you out.   Also, the module is short, which supports the Trailhead goal of helping customers learn quickly and  efficiently. The amount of text and information is minimal and focused on only the task at hand. A  note lets readers know that there are other ways to do this same task, but doesn’t confuse them by  going into that right now.          p. 10 
EXAMPLE 10: Using Formula Fields Trailhead Unit      ABOUT THIS EXAMPLE  Audience: Admins  Goal & tone: This section within the Formulas & Validations module introduces admins to formula  fields using simple, conversational language. The description also aptly uses several real-world  business examples.  Trailhead units engage users by combining our voice and tone with simple visuals, inline videos,  interactive challenges, and links to additional resources.      p. 11 
EXAMPLE 11: Admin Video Setup Banner      ABOUT THIS EXAMPLE  Audience: Admins  Goal & tone: This video banner alerts admins using Lightning Experience that parts of the video  show the old UI.  The banner anticipates a potential pain point (finding a feature that isn’t in the new UI), and offers a  solution. The banner also displays the icons for the UI elements (Setup, Quick Find) it refers to.    EXAMPLE 12: Help Doc (Evaluate and Roll Out Lightning Experience for Your  Org)      ABOUT THIS EXAMPLE  Audience: Admins and end users  Goal & tone: This topic helps admins and end users find features they use in the new Lightning  Experience user interface.  p. 12 
Using casual and empathetic language, the introduction mentions the challenges that arise when  using a new user interface: "Diving into a redesigned app can be disorienting..." The language then  assures admins that we're here to help make the transition as painless as possible.      EXAMPLE 13: Profile Pic Callout Text      ABOUT THIS EXAMPLE  Audience: End users  Goal & tone: The callout text gently notifies users that their profile picture may appear pixelated, and  suggests a simple solution using lighthearted language.            p. 13 
EXAMPLE 14: Empty-State Text   Note: see more empty-state examples in Confluence.        ABOUT THIS EXAMPLE  Audience: Admins and end users  Goal & tone: This text indicates that audiences haven’t been set up in a community org, and  encourages community managers to create one.  Using a playful and supportive tone, the copy gently encourages the community admin to engage  with the feature, and describes the value of the feature without going into too much detail: "Why not  create one now, so you can get the right stuff seen by the right people?" The copy is paired with a  picture that plays on the idea of an empty audience and adds a humorous slant to the message.    p. 14 

More Related Content

Salesforce voice-and-tone

  • 1. Salesforce Product & Content  VOICE & TONE Guidelines  INTRODUCTION  OUR   VOICE  WRITING   GUIDELINES  OTHER   RESOURCES  VOICE   &   TONE   EXAMPLES      INTRODUCTION     Why do we need voice and tone guidelines?  To connect with our customers, we need to talk in a way that resonates with them. The right voice  makes people feel at home through content that speaks their language.      How is voice different from tone?    ● Voice reflects our personality. It’s what we say.  ● Tone is the way we speak. It’s how we say things.    Our voice stays consistent across all of our content. Tone expresses the mood or feeling—which  should change based on your audience and the situation.      OUR VOICE, TONE, & AUDIENCE   When writing for Salesforce, our voice is always:   ● Honest: Trust is our #1 value, and we’re truthful in our writing.  ● Clear: Our writing is concise and easy to understand.  ● Fun: We’re dedicated to conversational, upbeat language.  ● Inspiring: We help people live their best lives, and our writing harnesses that genuine emotion.  p. 1 
  • 2. Take a look at our Corporate Voice and Tone to learn more about our company values.  Adapting your tone  Again, while our voice (our personality) doesn't change, we adjust our tone based on the audience.  For example…  ● Admins like encouragement and the occasional "You did it! Good job." ● Developers, not so much. They'd prefer we just get to the point, and they like it when we're honest about “gotchas.” ● New end users can be intimidated by all that’s in Salesforce. They need approachable, step-by-step introductions to terms and concepts. ● Salespeople don’t have time for lots of text. They need to get in, find what they need—and get right back to closing those deals!. See our voice & tone examples to see where these different tones are appropriate.  WRITING GUIDELINES  Part of what makes Salesforce documentation special is the way we talk to the reader. It  doesn't sound like enterprise software documentation. It sounds more like a conversation  with your buddy. With that in mind, here are some tips for writing “the Salesforce Way.”  Be concise.  ● Use as few words as possible. Avoid unnecessary and redundant information. ● Focus on user goals; make sure that you create content for an actual use case. ● Avoid large blocks of text. Avoid long, complex sentences. Be conversational.  ● Use natural, conversational language with a friendly, upbeat tone. ● Contractions are OK. ● Write from the users' perspective to help them accomplish tasks. ● Avoid developer-focused terminology, unless you’re writing for a developer. Be direct.  ● Use plain English. Avoid buzzwords, jargon, and words you wouldn't say in person. ● Use active voice, and avoid complex verb structures. ● Refer to user-interface elements by their literal names, not variations thereof (e.g., “click Submit” vs. “then save it”). Be positive.  ● Whenever possible, phrase sentences positively, not negatively. Negative: The mini view doesn't appear if the record in the detail view doesn't have any records associated with it. Positive: The mini view appears when the record in the detail view has associated records. p. 2
  • 3. ● When describing feature improvements, focus on new benefits to users, rather than on the  design problems they addressed.   Example: We’ve made important improvements to the side panel that increase your users’  productivity.    Be clever. But don’t try too hard to be funny.  ● Have fun—it’s part of our brand! But use humor judiciously, and know your limits. (Not everyone’s  a natural comedian.)  ● Focus on clear, concise content over clever language. Make sure content is understandable  independent of any witticisms.  ● If you do use jokes, keep them “family-friendly” and inclusive. (For instance, don’t make jokes  about dads unless you make jokes about moms, too.)    Give information “just-in-time.”  ● Introduce required conceptual information only when the user is performing the related task.    ● Explain business rules or constraints only when the user encounters their constraining effects.    Watch out for cultural references.  ● Be careful with allusions or culturally-specific language that may be lost on a diverse audience.    ● If you use any idioms in the UI, clarify them in a code comment for the localization team.    Use please sparingly.  ● Use please only when asking the user to do something inconvenient or when the system is to  blame.   Example: The export process may take a while. Please wait until the process completes.    Avoid sorry.  ● Use sorry only in error messages that result in serious problems for the user (for example, data  loss, the user can’t continue to use Salesforce, or the user must contact Support).   Avoid: Sorry, but you must supply a search string of at least two characters.  Better: Sorry, but you must exit and log in again.  ● Before you use sorry in UI text, ask yourself if we could change the design to avoid the situation.    Use exclamation points sparingly.  ● Use exclamation points to be encouraging or generate excitement.   Example: Almost there! [To show progress during a process.]  ● Don’t use exclamation points in error messages, confirmation messages, or instructional text.  Avoid: Your changes were saved!     Design text for easy scanning.  ● Users often scan rather than read, so put the important points first.   Put actions before explanations.    ● Use short bulleted lists.    ● Assume that after users have figured out what they need to do, they immediately stop reading  and do it.   ● Use See Also links at the end of topics to refer users to additional, related information.  p. 3 
  • 4. Provide clear instructions for users to correct errors.  ● For error messages, give the user clear instructions on how to correct the error. Example: This Self-Service username already exists. Choose a unique Self-Service username. ● Avoid phrasing that blames the user or implies user error. Passive voice can be appropriate in messages to achieve this purpose. Avoid referring to the location of items on a page.  ● Don’t use below, following, above, or other directional words to refer to the location of elements on a page. ● Exception: In walkthroughs, and in error message where a user has clearly missed a button or control, directional instructions can be helpful for many users. OTHERRESOURCES  Trailhead: Writing Style badge (get it!)  UX: Lightning Design System   p. 4
  • 5. VOICE & TONE EXAMPLES  These examples help you apply the voice and tone guidelines for different audiences and scenarios.  EXAMPLE 1: Salesforce1 App (Phone)  Navigation menu callout (top left)  Search callout (top right)  ABOUT THIS EXAMPLE  Audience: First-time Saleforce1 Mobile app users  Goal & tone: The goal is to let users know what the navigation menu and search icons do, and  generate enthusiasm for using the app. Since it’s a mobile app, the text is minimal, and the tone  is friendly and conversational: “Here’s your stuff!”  p. 5
  • 6. EXAMPLE 2: App Quick Start    ABOUT THIS EXAMPLE  Audience: New Salesforce admins  Goal & tone: The goal is to help new admins get started quickly. We want their first experiences with  Salesforce administration to be successful and productive.   “Tell us about your app, and we’ll whip up the basic parts for you.”  The tone is conversational and human (“us” and “we’ll”). We want them to know we’re here to help:  just give us some info, and—voila!—we’ll give you an app.   “You can always change this and other labels later.”  “You can add more later.”  The text is reassuring: by telling users they can go back and make changes, we show that we  understand their fears as new users, and let them know they’re not doing anything they can’t fix later.      EXAMPLE 3: Widgets Message Block      ABOUT THIS EXAMPLE  p. 6 
  • 7. Audience: Admins  Goal & tone: The goal is to quickly communicate what widgets do and their benefit for admins. The  tone is direct and conversational, but not overly chatty.       EXAMPLE 4: Walkthrough (CRM Free Trial, Initial Tour for Sales Reps)      Accounts, Contacts, and Leads Tabs    Opportunities Tab    Reports and Dashboards Tabs    Setup Link    Walkthrough Side Panel    Import Contacts Widget      ABOUT THIS EXAMPLE  Audience: Sales reps evaluating Salesforce  Goal & tone: The goal of this walkthrough is to drive purchase and/or adoption of Salesforce. We  want our customers to know that we get them: Sales reps are busy and driven, so the tone is  direct and clear rather than chatty, and uses the same words they do. It also empathizes with  their pain points: a messy desk and a busy schedule. It also acknowledges what’s important to  reps: identifying and closing deals, hitting quota.   p. 7 
  • 8. Notice how we’ve used the same tone in both heading and text, and that we end with a call to  action: “Import your contacts now!”      EXAMPLE 5: Release Notes (Communities)    ABOUT THIS EXAMPLE  Audience: Admins  Goal & tone: The goal of this section is to let admins know that they have more flexibility and  control over their community page layouts. It’s focused on what admins can do now. The tone is  energetic, positive, and user-centric: “Looking for more granular control…?” “that’s exactly what you  get!”  The section goes on to describe the various layouts (text omitted), concluding with some concrete  examples to help admins get their heads around it: “Let’s say you create three pages for your  upcoming Spring campaign....”     EXAMPLE 6: Quick Start Developer Text      ABOUT THIS EXAMPLE  Audience: Developers  p. 8 
  • 9. Goal & tone: The goal of this developer guide is to encourage developers to create their own apps  for the Salesforce1 mobile app. Here’s a topic that sets the right tone. Brief, to the point, and  acknowledges the fact that readers (developers) would rather not be reading.      EXAMPLE 7: Lightning Experience Chatter Publisher      ABOUT THIS EXAMPLE  Audience: Chatter users  Goal & tone: The goal of the ghost text is to tell users what kind of information they can enter in a  Chatter post, and the ellipsis invites users to tell readers about their situation.      EXAMPLE 8: Salesforce Mobile SDK Guide    ABOUT THIS EXAMPLE  Audience: Developers  Goal & tone: The goal of this developer guide is to encourage developers to create their own apps  for the Salesforce1 mobile app. The tone is light, friendly, conversational. It starts a sentence with  "But" instead of "However." It takes on an empathetic, reassuring tone with the phrases, “don’t worry,”  and “you should be able to follow along just fine.” It uses casual, everyday language, “admin,” instead  of “administrator.”      p. 9 
  • 10. EXAMPLE 9: Getting Started with Apex Trailhead Module    ABOUT THIS EXAMPLE  Audience: Developers  Goal & tone: The goal of this Trailhead module is to introduce developers to Apex. The  conversational and relaxed tone makes readers feel comfortable trying out a new programming  language. For example, it reassures readers that we’re in this together by starting the module with  “Let’s.” The phrase “on the fly” and the adjective “handy” reinforce the friendly tone—it’s like the  programmer sitting next to you is helping you out.   Also, the module is short, which supports the Trailhead goal of helping customers learn quickly and  efficiently. The amount of text and information is minimal and focused on only the task at hand. A  note lets readers know that there are other ways to do this same task, but doesn’t confuse them by  going into that right now.          p. 10 
  • 11. EXAMPLE 10: Using Formula Fields Trailhead Unit      ABOUT THIS EXAMPLE  Audience: Admins  Goal & tone: This section within the Formulas & Validations module introduces admins to formula  fields using simple, conversational language. The description also aptly uses several real-world  business examples.  Trailhead units engage users by combining our voice and tone with simple visuals, inline videos,  interactive challenges, and links to additional resources.      p. 11 
  • 12. EXAMPLE 11: Admin Video Setup Banner      ABOUT THIS EXAMPLE  Audience: Admins  Goal & tone: This video banner alerts admins using Lightning Experience that parts of the video  show the old UI.  The banner anticipates a potential pain point (finding a feature that isn’t in the new UI), and offers a  solution. The banner also displays the icons for the UI elements (Setup, Quick Find) it refers to.    EXAMPLE 12: Help Doc (Evaluate and Roll Out Lightning Experience for Your  Org)      ABOUT THIS EXAMPLE  Audience: Admins and end users  Goal & tone: This topic helps admins and end users find features they use in the new Lightning  Experience user interface.  p. 12 
  • 13. Using casual and empathetic language, the introduction mentions the challenges that arise when  using a new user interface: "Diving into a redesigned app can be disorienting..." The language then  assures admins that we're here to help make the transition as painless as possible.      EXAMPLE 13: Profile Pic Callout Text      ABOUT THIS EXAMPLE  Audience: End users  Goal & tone: The callout text gently notifies users that their profile picture may appear pixelated, and  suggests a simple solution using lighthearted language.            p. 13 
  • 14. EXAMPLE 14: Empty-State Text   Note: see more empty-state examples in Confluence.        ABOUT THIS EXAMPLE  Audience: Admins and end users  Goal & tone: This text indicates that audiences haven’t been set up in a community org, and  encourages community managers to create one.  Using a playful and supportive tone, the copy gently encourages the community admin to engage  with the feature, and describes the value of the feature without going into too much detail: "Why not  create one now, so you can get the right stuff seen by the right people?" The copy is paired with a  picture that plays on the idea of an empty audience and adds a humorous slant to the message.    p. 14