Write The Docs EU — Kelly O’Brien — Engage or Die: Four Techniques for Writing Indispensable Docs

Kelly O'Brien

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Engage to earn readers’ trust.

  1. Understand where they’re coming from.
  2. Sympathize with their frustrations.
  3. Know what they need to accomplish.
  4. Help them solve their problems.

Death by Apathy. Our readers are like teenagers. Write with empathy to prevent apathy. What’s important to them? (Spoiler: It isn’t about how the system is set up.)

Technique #1: Put your readers first. Build a mental picture of the reader.

Death by Alienation. Readers are sensitive. Don’t talk down to them, or they’ll ignore you.

Technique #2: Mind your tone. Formality. Balance of an authoritative and relaxed, conversational voice. Consider the company culture, purpose, and tech savviness of your readers. Be deliberate and consistent so they can see that you sympathize.

Death by Impatience. Don’t make them hunt for answers.

Technique #3: Lead with the problem. Make it clear to your readers what they’ll learn from each portion of your docs. Remind yourself:

“If I read this, what’s in it for me?” (WIIFM) This is also the secret to reader engagement. Add this to the beginning to each section later in the writing process.

Death by Disorientation. If your reader wonders, “Why are we talking about this?”, beware.

Technique #4: Use Powerful Pointers. “Key sentences that recap, state, or foreshadow the information you’re presenting.” Or, more formally, contextual structure. Avoid a “monolithic flood of information”.

These pointers for your readers:

  • Their needs come first.
  • They aren’t alone.
  • Communicate WIIFM to them.

Published by

Bryan Villarin

Bryan is a Happiness Engineer at Automattic. He's also a photographer, card magician, and cat whisperer. (Thanks to my friend and colleague Steve Blythe for the sweet photo!)

Talk to me, Goose

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s