Engage or Die: Four Techniques for Writing Indispensable Docs

No matter how detailed, how thorough, or how well organized you make your documentation, if it fails to engage your readers, they won’t stick around long enough to hear what you’re telling them. By borrowing time-honored techniques from professional nonfiction writers, you can make sure that your readers connect to your writing, right off the bat.

In this talk, I introduce four writing techniques, and show you how to use them to build docs that your readers will relate to and rely on.

Transcript

1. Four Techniques for Writing Indispensable Docs ENGAGE OR DIE Kelly O’Brien
2. //Kelly O’Brien Engagement 101 to engage, verb to hold the attention of - Merriam-Webster.com Good start, but for docs, engagement also means earning our readers’ trust.
3. //Kelly O’Brien Engagement 102 Our readers need to trust us to do four things: • understand where they’re coming from • sympathize with their frustrations • know what they need to accomplish • help them solve their problems Otherwise...
4. SPECIFIC FAILING Slide body copy goes here. Cause of Death: APATHY Think of readers as teenagers. If they detect that they have ceased to be the center of attention, they will tune you out. Forever. (Unlike teenagers.) Death By
5. Put your Readers’ needs First Prevent apathy with empathy. Everything we put on the page must convince our readers that we care—a lot. Technique #1:
6. //Kelly O’Brien your Readers’ Needs The first step to getting into your readers’ heads is to recognize the following: The things that are most important to your readers are not necessarily the same as the things that are most important to you.
7. Reader Experience Approach your readers as users. What do they care about? What do they struggle with? What do they need? These questions help you understand your readers, making engagement a lot easier.
8. alienation Readers are a sensitive bunch. If they ever feel that you’re not on their side, they’ll put your docs down and never bother with them again. Death BY
9. Mind Your Tone Your voice is one of your most powerful tools—use it wisely. Tiny adjustments to your tone can make a huge difference to your readers. Technique #2:
10. //Kelly O’Brien Formality Spectrum Tone of voice in your docs is about formality. Think of it as a spectrum with an academic, authoritative voice at one end, and a relaxed, conversational voice at the other. Find a place somewhere in the middle.
11. Finding a Balance There are three big considerations for tone: • What is the company culture like? • What purpose do your docs serve? • How tech savvy are your readers? Whatever tone of voice you go with, employ it deliberately and consistently to make it clear that you sympathize.
12. IMPATIENCE The last thing your readers want is to do is hunt for answers. If it takes your readers too long to find what they need, your docs are as good as dead. Death by
13. lead with the problem Organize your content according to the problems it solves. Make it clear to your readers what they’ll learn from each portion of your docs. technique #3:
14. //Kelly O’Brien What’s in it for me? Run this test on your docs: Pretend to be your reader and ask: “If I read this, what’s in it for me?” Asking this question gives you the WIIFM (what’s in it for me)—the secret to reader engagement.
15. WIIFM, Part II Make the WIIFM clear to your readers...by simply telling them what it is. This happens later in the writing process. Get everything on the page first, then go back and make the WIIFM clear, showing your readers you know what they need.
16. DISORIENTATION Readers have short memories. If your reader ever wonders ‘Why are we talking about this?’ your docs are in trouble. Death by
17. Use Powerful Pointers Use pointer sentences to help your readers orient themselves. Pointers are key sentences that recap, state, or foreshadow the information you’re presenting. technique #4
18. //Kelly O’Brien INFRASTRUCTURE Pointers give your readers a contextual structure for what they’re reading. When sharing a lot of information, pointers show your readers how you’re going to help them solve their problems.
19. //Kelly O’Brien ENGAGEMENT BONUS +3 Structural benefits aside, pointers also give you a chance to use the other 3 techniques: • Show that your readers’ needs come first • Remind your readers they’re not alone • Communicate WIIFM to your readers
20. 1: PUT YOUR READERS FIRST 2: MIND YOUR TONE 3: LEAD WITH THE PROBLEM 4: USE POWERFUL POINTERS 4 TECHNIQUES for INDISPENSABLE DOCS
21. Thank You! Questions? I’m all yours! And if something occurs to you later, please feel free to reach out. I’m online at all of these places: http://obrieneditorial.com kobrien042@gmail.com @OBrienEditorial //Kelly O’Brien Credits (Awesome) Vector Art: Freepik.com. Fonts: ADAM, by Shrenik Ganatra and the Roboto family by Christian Robertson.