Writing Guides When Readers Need Context

When people ask me to write documentation, they usually envision a reference. References that list and describe are good when someone wants to look up an individual feature, function, statistic, or fact.

A guide is a form of documentation that informs people with more context. When done well, they’re great for educating people who know little about your product or service. References provide facts. Guides take longer and lead people to comprehension and confidence.

Write about features with workflows, not features alone

Working for UXPin in 2016, I identified the need for better onboarding. Our tech support team was answering the same questions every week, and I wondered if better documentation could prevent most queries before they arrived.

I started the UXPin User Guide, which has since been replaced (yet still exists online), by jotting down everything I knew about the product. I organizing my notes based on features and selling points, and write articles to suit:

  • The User Interface
  • Basic Elements
  • Animations
  • Multistate Elements
  • Interactions

The feature approach lead to a decent reference for people who knew what to look for. That was a mistake. My intended audience didn’t need features. They needed guides.

While references define individual parts, a guide takes people through processes that use the features, explaining them as they go. Compare this list to the previous one:

  • Using the User Interface to find Basic Elements
  • Animating Basic Elements
  • Adding Interactions to Basic Elements

References provide facts and data, while guides explain with a process. Pantone has many color samples, including chip books and an online color finder. They also have a guide that explains their systems for people who don’t know how to choose, or have questions.

In documentation, “how to get stuff done” always beats “our features are great.”

Try writing in terms of case studies or practical use cases — real examples of the processes and tools in action. For UXPin, I tried to reference separate how-to articles I’d already written, though people appreciated quick examples in the guide itself.

After UXPin cut half of their marketing team in 2017, including myself, the User Guide remained online as a definitive reference for more than a year. As of early 2020, it lives on in addition to a new official set of feature-based docs.)

Choose the right voice for the job

In my experience, no one reads internal documentation more than new-hires. They benefit from guides that encourage as well as inform.

New people within an organization have a different mindset than end users or the general public. The right documentation style will make them feel welcome and inspire confidence, which facilitates learning. People are more receptive to education when they feel like you’re paying attention to them, like you care about them.

While documenting an internal system at Walmart Labs, I suggested writing a tutorial that explained the difference between two similar, but unrelated, processes. To set the tone, the draft used an informal voice.

Here’s an example of formal voice.

“Originally, feature X was designed to enable people to Y.”

What makes it formal? It refers to abstract entities — “was designed” implies without naming a designer, and “people” is a vague crowd somewhere. Passive voice is a shade less personal than active.

Here’s the same sentence with conversational voice.

“Developers originlly built feature X to let you do Y. But you’ll get better results if you follow this shortcut ….”

Not only does this educate the reader, but it subtly brings them onboard. Sharing shortcuts, hacks, and effort-saving makes people confident that you’re on their side, giving them information beyond what ordinary users know.

This chart shows the differences between a friendly, casual voice and a formal, impersonal voice.

Write as if you are confiding in her/him. This isn’t some generic feature list for the public. You’re making a new coworker feel welcome with your writing. I’m on your side. Here’s what I’ve learned. Let me help you get up to speed. We’re in this together.

In the end, Walmart Labs opted to explain their processes through a required onboarding article rather than elaborate on the reference docs. Sometimes people set priority on meeting deadline, and writing new documentation takes time.

Don’t joke

Of course, it’s possible to go overboard with friendly onboarding.

Regardless of their mindset, remember that people who read documentation don’t want to. The docs is a means to a goal — namely, using what the documentation describes. Everyone who reads docs is either in a hurry or dreading the read. Sometimes both.

Unless it’s built into a game, don’t gamify your documentation. You can write docs with a friendly or encouraging voice, but not by adding bulk. Consider this example:

“Using this feature will prevent your widget production process from turning into a skit worthy of Monty Python. Here’s how you can always look on the bright side of life.”

Jokes alienate certain audiences. Not everyone is familiar with The Life of Brian, and jokes without context are like images without alt attributes.

Also, people who don’t like puns interpret them as desperation. That erodes confidence in you. They’re not worth the risk.

“Using this feature will streamline the widget production process.”

This example trades fun for expediency. People get the information they want, even though the writing feels more generic. Is there a middle ground? Sort of.

Injecting humor only works if:

  • You continue to sprinkle in references
  • The running theme fits the feature’s benefit

Otherwise, don’t joke about it.

Going forward

Guides and references each have their place, and can work together for towards a common goal. But it’s a mistake to favor one over the other. Get to the point with references for people who want quick facts. Lead people through the basics with guides.