Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Engage or Die: Four Techniques for Writing Indi...

Kelly O.
March 31, 2014

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.

Kelly O.

March 31, 2014
Tweet

More Decks by Kelly O.

Other Decks in Technology

Transcript

  1. //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.
  2. //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...
  3. 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
  4. 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:
  5. //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.
  6. 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.
  7. 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
  8. 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:
  9. //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.
  10. 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.
  11. 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
  12. 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:
  13. //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.
  14. 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.
  15. DISORIENTATION Readers have short memories. If your reader ever wonders

    ‘Why are we talking about this?’ your docs are in trouble. Death by
  16. 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
  17. //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.
  18. //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
  19. 1: PUT YOUR READERS FIRST 2: MIND YOUR TONE 3:

    LEAD WITH THE PROBLEM 4: USE POWERFUL POINTERS 4 TECHNIQUES for INDISPENSABLE DOCS
  20. 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 [email protected] @OBrienEditorial //Kelly O’Brien Credits (Awesome) Vector Art: Freepik.com. Fonts: ADAM, by Shrenik Ganatra and the Roboto family by Christian Robertson.