5 Ways to Improve Your Help Docs


You know you need to beef up your help and documentation. Your users keep asking you to do it. The managers keep hounding you to do it. And your tech support people are desperate for you to do it.

But where do you start?

I spent some time in tech support when my career began but decided to specialize in documentation so that I could answer questions before they were asked. Now that I’m on the documentation team at Salesforce, let me share some of my insights into how to improve the help you have and win accolades from tech support, management, and even users.

Call a spade a spade: Use the correct terms

Are you calling it a customer, a lead, or a contact? At times these words are used interchangeably, but they really have specific meanings. All three words can basically mean the same thing, but they also have specific meanings. A contact is a person you’ve met. A lead is someone who has expressed interest in your product or service. And a customer is someone who has done business with you.

Whatever you call it, make sure you call it the same thing everywhere. Otherwise, your users are confused by what you mean.

Horses, not zebras: Focus on the common things your users do

You have the most extensive documentation ever written about how to enter that complicated order, so why aren’t the sales folks happy? Maybe it’s because they only get that order once a month, and the instructions are more confusing than the types of orders that they get three times a day.

The lesson? Ask your users what they work on all day. Creating new accounts? Updating schedules? Tracking opportunities?

Then make sure your content for these tasks is thorough. If there’s a shortcut for creating new accounts accurately, or a sweet technique for updating schedules easily, document it! Your users will love you for making their lives easier.

The squeaky wheel needs the grease: Know your user’s pain points

What trips up new users over and over? What do even experienced users have questions about?

If your company has standardized on 10 opportunity sales stages, what does stage 1 mean? Does it mean that it’s the first time they’ve contacted you, or the first time you’ve contacted them?

Managers run reports on these stages, so it’s important to be accurate. Where can a user find out which one to choose? Your goal is to make sure the info is in help!

Whether it’s choosing the correct sales stage for an opportunity or emailing intro marketing collateral, make sure that you’ve got all the steps and details in your help. Having the info right at their fingertips means users don’t have to wonder what to do.

So find your squeaky wheels: What are users still calling and emailing about? Address those questions, and see the call and contact volume go down.

A spoonful of sugar makes the content go down: Keep it short and sweet

Great! Your users know that you’ve documented everything anyone needs to know about tracking opportunities. Then they open the help, see five pages of dense text, and close it before they’ve read the first sentence. What happened?

You know the topic can be complicated, but you don’t have to make it look that way!
If the help is too long and looks too complicated, users won’t read it.

Instead, make it short and sweet, and keep ’em coming back for more. Focus on the most important tasks and info, and put “nice to know” content in another topic. Use bold type, numbered steps, and bulleted lists to make the information accessible. Include relevant graphics and screenshots to break up the page and ensure that your users know what screen they should be on. And don’t forget that the YouTube generation loves short videos to show them what to do!

Basically, keep it easy, and they’ll keep coming back.

Stay in the loop: Get feedback before and after

When you start on a large project—like coordinating a block party or rolling out a new Salesforce release—you want to hit the ground running. Talk to people who were involved in similar projects to see what went well and what didn’t. Then you can make sure to do more of the good stuff and none of the bad.

Similarly, there’s no better way to get great content than by testing it with real users. Have representatives from typical user groups read and use the info during their work day, and confirm whether it’s correct, complete, and, above all, useful.

What do they love and what isn’t so popular? Do more of the first and less of the second.

Remember though, your job isn’t done after you’ve released user-approved content. As the months pass, your company’s processes change. A new sales stage is introduced. The order entry process is simplified. In short, instructions become outdated.

For all these reasons, give users a way to let you know when content needs to be updated. They’re your frontline defense against stale, out-of-date info.

And there you have it: five ways to improve your help docs and make everyone’s life easier. Get ready for all the accolades!

Check out this great webinar on documentation by our #awesomeadmin community member Amber Boaz!

Cloudy standing with a laptop next to text that says "Admin Best Practices User Management."

Admin Best Practices for User Management

Managing users is a core Salesforce Admin skill. One element of this skill is ensuring that each user has access to the right data so they can do their job. As admins, we also need to protect data that may be confidential, preventing users who don’t need to access that data from viewing, editing, or […]

Introducing Customer Service Incident Management

Build Customer Trust with Customer Service Incident Management

Since COVID-19, we’ve witnessed a remarkable transformation as more companies go digital to run their business from anywhere. While digital transformation has enabled so many companies to innovate in their service offerings, it has also introduced a new challenge: ensuring availability and uptime of those services. The reality is that a service disruption is inevitable. […]

Cloudy, Astro, and a snowman next to text that says, "LeeAnee's Ultimate 2021 Design Thinking Playlist."

LeeAnne’s Ultimate 2021 Design Thinking Playlist

As Salesforce Admins, we’re constantly working to design engaging and delightful user experiences. Whether we’re building custom pages with App Builder, customizing a mobile experience, or creating a useful and compelling dashboard, design is core to the work we do. With all of the new product releases and enhancements happening on the Salesforce Platform, especially […]


Have an Idea for a Story?

We are all about the community and sharing ideas.
Do you have an interesting idea or useful tip that you want to share?