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.
- Understand where they’re coming from.
- Sympathize with their frustrations.
- Know what they need to accomplish.
- 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.
All Narfed Up 