Learn the Guidelines
After completing this unit, you’ll be able to:
- Describe general tech writing guidelines.
- Explore additional Salesforce writing guidelines.
- Explain when (and when not) to use please, sorry, and exclamation points.
OK, you’re in your customer’s shoes. Now what?
For you admins reading this, we know you often need to teach your colleagues how to use Salesforce. You might do this in person, but you also might provide information in an email, a wiki page, or even within the app itself. Do you want those communications to bore your team to death, or do you want something more engaging?
We’ll skip some of the mechanics, like making an outline, writing drafts, and making edits. Let’s explore some of our style guidelines and precepts.
What’s a writer’s primer, you ask? It’s not the coat of paint you apply to your neighborhood writers when they start peeling from old age and too many run-on sentences. It’s a short set of guidelines that are generally seen as valid by those who write for a living (especially technical writers). So let’s hit you with a few:
- As Mr. Strunk (of The Elements of Style fame) so succinctly put it: “Omit needless
- Focus on your audience’s goals. Are you writing content for an actual use case or project? (If not, why are you writing it?)
- Avoid large blocks of text (z-z-z). Avoid long-winded, labyrinthine sentences.
- Use plain English. Avoid jargon and $5 words (like labyrinthine) that you wouldn't say in person.
- Use the active voice. Passive voice is to be avoided.
- Avoid complex verb structures. If I were to explain this, I might reach for a more direct
Give “Just-in-Time” Information
- Don’t bore your audience with conceptual information for its own sake. Present it only when it’s related to the task at hand.
- Explain business rules or constraints only when your audience might be encountering them.
Design Text for Easy Scanning
- Users often scan rather than read. Put the important points first.
- Use short bulleted lists.
- Put actions before explanations.
- Assume that once users figure out what they need to do, they immediately stop reading and go do it.
- Don’t be euphemistic. Refer to user interface (UI) elements by their exact names in the UI.
- Provide clear instructions for users to correct errors or follow a procedure.
Now let’s review some guidelines that are unique to Salesforce. Remember all that talk about friendly, approachable language? Here are a couple ways to get there:
- Use a friendly, upbeat tone. (Don’t gush! But perky’s OK.)
- Don’t be afraid of contractions.
- Avoid technical language. Unless you’re writing for techies.
- Whenever you can, accentuate the positive.
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.
- When describing feature improvements, focus on the benefits to users, not the design
problems (oops) that they address.
Example: We’ve made awesome improvements to the side panel that increase your users’ productivity.
Use Exclamation Points Sparingly
Why use exclamations sparingly?! Because this looks odd! No one talks this way! I like artichokes! Let's write some content!
As you can see, this copy looks weird, and not in a good way. Limit exclamations to places where they'll deliver maximum impact.
- Use exclamation points only to be encouraging or to generate excitement.
Example: Almost there! [To show progress during a process.]
- Don’t use exclamation points in error messages, confirmation messages, or instructional
Avoid: Your changes were saved!
Please Don’t Say Please
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: Please enter the account name.
And Don’t Say You’re Sorry (Unless You Really Mean It)
- Use sorry only in error messages that result in serious problems for the user (for
example, data loss, a screen freeze, or the need to contact Support).
Example: Sorry, but you must exit and log in again.
Avoid: Sorry, but you must supply a search string of at least two characters.
- Before you use sorry in UI text, ask if a design change could avoid the situation.