Write the Docs: Kelly O’Brien – Engage or Die: Four Techniques for Writing Indispensible Docs

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Kelly runs O’Brien Editorial, a technical writing business that works on documentation for small Drupal shops and large enterprises. She started as a journalism major in college and wrote about everything from food culture to trends in eco-construction materials. Through that experience she learned about how to target writing to your audience. In other words, how to engage your readers.

Engagement is about holding your readers’ attention but also means earning the trust of your readers. With documentation you want readers to rely upon your documentation for help. That starts with trust.

Readers must trust that you understand where they’re coming from. That you sympathize with their frustrations. That you know what they need to accomplish. That you’ll help them solve their problems.

If you don’t do those 4 things readers will ignore your docs. Kelly calls this Doc Death. There are 4 kinds.

The first is Death by Apathy. Think of readers as teenagers; if they detect that they have ceased to be the center of your universe they will tune you out. To fight this you need to put your readers first. Prevent apathy with empathy. The first step is to recognize that the things that are most important to your readers are not necessarily the same as the things that are most important to you. To learn what’s important you can ask what they care about, what they struggle with, and what they need from you.

Death by Alienation is the second form of Doc Death. Readers are a sensitive bunch. If they ever feel that you’re not on their site they will put your docs down and not touch them again. Your voice is one of your most powerful tools to combat this. Use it wisely. Tiny adjustments can make a huge difference to your readers. In your docs tone of voice is about formality. It’s a spectrum between academic and relaxed. The goal is to find a place somewhere in the middle. To do that you should take 3 things in to account: the company culture, the purpose of your docs, and the tech savviness of your readers. Whatever tone of voice you choose, be deliberate about it and employ it consistently.

The third type of Doc Death is Death by Impatience. The last thing your readers want to do is to hunt for answers. If it takes your readers too long to find what they need, your docs will be ignored. Organizing your content helps fight this. You should lead with the problem that the document solves. It makes it clear to your readers what they’ll learn by reading. It helps if you ask, “If it read this, what’s in it for me?” The secret to reader engagement is WIIFM: What’s In It For Me. You can make this clear to your readers by simply telling them. This should happen later in the writing process. The first step is to get everything on the page; then you can go back and make the WIIFM clear.

The last form of Doc Death is Death by Disorientation. Readers have relatively short memories. If your reader every wonders “Why are we talking about this?” your docs are in trouble. The solution is to use powerful pointers. Using pointer sentences helps your readers orient themselves. Pointer sentences recap, state, or foreshadow the information you’re presenting. They create a contextual structure for what readers are looking at. They also allow you to show that your readers’ needs come first. They remind your readers that they’re not alone. Finally, they communicate the WIIFM to your readers.