Help me help you: How we design help documentation at Envoy

Abby Beard
Envoy Design
Published in
4 min readApr 10, 2018

I started at Envoy three years ago with one purpose—to create content that makes users more successful. While there are many aspects to this endeavor, I’ve come to truly love what’s maybe the least sexy part of any product.

The help center.

Why? Because it can make or break an experience. I’m sure there’s been a time where you had to do something at work that was intimidating. At startups, this is part of everyday life. We so often teach ourselves how to use new tools and create new processes. So whether you’re designing your first email campaign or hitting merge on your first branch, good documentation can make you feel like “I got this!”

To that end, I’d like to share our documentation ethos with you. Like everything else, it’s a work in progress. But if you glean anything that helps you help your users, it’s well worth sharing.

Meet users where they are

Come from a place of empathy

Think about the mindset of a user who’s visiting the help center, and how they’re likely to be experiencing a moment of confusion or frustration.

This applies to copy, yes, but also to design. Think about keeping the layout simple, avoiding superfluous illustrations, and watching out for colors that might “scare” a user (an especially tough challenge when your brand color is red!).

Be brief and accurate

Users are coming to the help center to get what they need and then get out. Help articles are not the place to sell the product or use marketing speak.

  • Needs work: Envoy Visitors is a digital visitor management system that’s changing how visitors sign-in at workplaces around the world.
  • Better: With Envoy Visitors, your guests sign in on an iPad instead of in a paper logbook.

“Tell users what they need to know, but don’t condescend.”

Be plainspoken and don’t assume

Remember that your team built the product. You’re inherently closer to it than the user will ever be. Tell users what they need to know, but don’t condescend.

  • Needs work: It’s easy to add a printer and configure badges right from your dashboard.
  • Better: Envoy Visitors can print guest badges automatically. To set up badge printing, follow these steps.

Your dummy data matters

Hi there, Alexa!

For documentation screenshots and examples, create a demo account with faux user personas. At Envoy, our dummy account admin is Alexa Beckfield.

She and a host of others “work” at the faux company Second Street Labs. They even have recurring visitors from another faux company.

Second Street Labs is our go-to test account to cite in all articles. It prevents us from further confusing users by using our own company name or pop culture references in screenshots and product descriptions.

“Remember that not everyone uses your knowledge base the same way.”

Master searchability and categories

Search is key. Today’s best help centers make the search bar the main focal point and have smart indexing systems that focus on synonyms. For example, if a user searches for “messages” but your articles refer to “chats,” be sure to return their anticipated results.

But remember that not everyone uses your knowledge base the same way. For those who like to browse, it’s important to sort articles into relevant categories.

While this may seem obvious, it doesn’t appear to be something that many ready-built help center tools focus on.

By default, many tools display only the first few articles in each category. This means that users have to work harder to find what they’re looking for. Opt instead for a layout that shows all the article titles at a glance.

Don’t just focus on the help center

The quickest way to provide helpful information is through in-product documentation. Heavy handed product copy can get overwhelming, so it’s important to keep inline tips limited in both number and length.

It’s crucial to incorporate copy into the design process in an intentional way—don’t just add a tip anywhere. If you do, it will feel like a band-aid solution to a UX problem. When design and documentation work together, your team can determine a cohesive strategy of where to show inline tips and where to link out to richer documentation.

Does the design team have a hand in your company’s documentation? Do you wish they did? Let us know why or why not.

Thanks for reading! Be sure to visit envoy.design and subscribe to get notified when we publish something new.

--

--