This document discusses reactive writing techniques for rewarding and retaining users. It defines reactive content as documentation produced in direct response to a specific user problem. While reactive content satisfies immediate needs, it can be disorganized, outdated, and lacking context. The document recommends that writers identify user personas and pain points, deliver targeted help, direct users to the appropriate documentation, and use an accessible writing style. It provides examples of applying these techniques and concludes with exercises for audience members.
3. About me…
• Based in San Francisco –
salesforce.com
• 15 years in technical writing
• Contractor / full-timer/ lone writer /
team member
• Aon Insurance, Pacific Bell, Schwab,
Advent Software, salesforce.com
• Information design, writing, editing
• Two STC awards
4. Here’s what we’ll cover today
• What is reactive content, anyway?
• Why does it matter? What’s the problem?
• How can leverage the reactive model to
enhance our own doc and user assistance?
• Examples
• Exercises
5. So… what is reactive content?
• Defined: Documentation produced in direct
response to a single, specific, user-expressed
problem (the content creator’s or someone
else’s).
• Who writes it?
• Bloggers
• Members of user groups
• Our companies’ product support reps
• Not professional writers
6. So… what is reactive content?
• What’s so great about it? Why does it persist?
• Provides specific and targeted information
• Meets an immediate / urgent need
• Is often sympathetic and friendly
• How do our users find it?
• User communities
• Immediate Frantic Googling (IFG)™
(We’ve all done it.)
9. So what’s the problem?
Why should we care?
• Lots of reasons. While it often meets an
immediate need, reactive content can be:
• Hard to find
• Hard to understand
• Incomplete
• Out of date
10. So what’s the problem?
Why should we care?
• Unflattering
• Lacking context
• Expensive to our companies
• The first―and the last―documentation
our users see
• It satisfies a momentary need, but doesn’t
always provide additional value
12. What can we do?
First, think of it this way….
If you give a man a fish, you feed him for a day.
If you teach a man to fish,
you feed him for a lifetime.
-Chinese proverb
13. We want to do both.
• First, meet that immediate need to gain trust
• Get the user out of HELP mode…
• … And into LEARN mode
• Keep our users in our product and our doc
• Create experts
• Create evangelists
14. But how?
• Five tools and techniques:
• Create personas
• Identify your user’s pain points
• Deliver help and user assistance
• Send users to the right kind of doc
• Use style to maximize the user’s experience
15. 1. Create user personas
Personas • Pain Points • Delivery • Right Doc • Right Style
• Defined: An archetypal user that represents a
larger group of users.
• Personas can include:
• A name and image
• Job and career path
• Demographics (age, education …)
• Psychographics (values, interests, cultures …)
16. 1. Create user personas
Personas • Pain Points • Delivery • Right Doc • Style
• Personas can include:
• Task flows and times spent
• Products and tools
• Performance measurements
• Pain points
• Doc and UA preferences
17. 1. Create user personas
Personas • Pain Points • Delivery • Right Doc • Style
18. 1. Create user personas
Personas • Pain Points • Delivery • Right Doc • Style
19. 2. Identify potential pain points
Personas • Pain Points • Delivery • Right Doc • Style
• Your Persona + Your Product.
What seems to be the trouble? Something…
• Brand new product or feature?
• Time-consuming?
• *Old, obscure, or buried?
• *Beyond the user’s typical workflow?
• *Beyond the user’s standard skills?
• *High stress or high exposure?
20. 3. Deliver help and UA
Personas • Pain Points • Delivery • Right Doc • Style
• Your Persona + Your Product.
Where does it hurt?
• A UI page?
• A multipage task or workflow?
• An interaction between tools?
• A product gap or missing feature?
21. 4. Send them to the right doc
Personas • Pain Points • Delivery • Right Doc • Style
Where is our user Support Phone # “Help!”
now, and where Mode
FAQ
do we want them
to get to? Reference
Task
What medium Task of Tasks
works best?
Map
Concept “Learn…”
Mode
Overview
22. 4. Send them to the right doc
Personas • Pain Points • Delivery • Right Doc • Style
Support Phone #
What’s the FAQ
sweet spot? Reference
Why? Task “See also”
• Recognizable Task of Tasks
topics
• In context
Map
Concept
Overview
24. Example: Data.com Clean Admin
Personas • Pain Points • Delivery • Right Doc • Style
• Here’s the challenge we faced.
• Product new in Salesforce, but…
• Enhancement / redesign of vendor product
• Users may or may not have experience with
vendor product
• Most administrators are sales managers,
not full-time administrators
• High stress / high exposure
27. 5. Use friendly, accessible style
Personas • Pain Points • Delivery • Right Doc • Style
• Encapsulate
• Deliver the smallest useful unit of information
• Make each topic answer a single question
• Tip: Use the journalists’ questions: who, what,
where, when, why, how, which
28. 5. Use friendly, accessible style
Personas • Pain Points • Delivery • Right Doc • Style
• Use minimalism
• Eliminate extraneous content―at all levels
• Craft titles that guide your users
• Doc one way and only one way to do something
29. 5. Use friendly, accessible style
Personas • Pain Points • Delivery • Right Doc • Style
• But don’t skimp!
• Include all required information
• Define key terms and make definitions easy to find
• Tip: Write wordy and edit down
30. 5. Use friendly, accessible style
Personas • Pain Points • Delivery • Right Doc • Style
• Use “factoring”
• Say it one way and only one way, every time
• Use parallel structure at all levels
• *Reinforce your information types with title syntax
• *Repeat sentence syntax to highlight new info
• Make list intros as detailed as possible
• Eliminate “synonyms”
• More factoring = time savings, less confusion!
31. Example: Factoring
Personas • Pain Points • Delivery • Right Doc • Style
Use title syntax to reinforce info types
Overview X Overview Accounts Overview
Data.com Overview
Concept Understanding X Understanding Clean Status
Understanding Data.com Licenses and
Limits
Map/Task of Tasks Setting up X Setting up Data.com
Setting up Forecasts
Task …ing X Adding Accounts from Data.com
Creating Role Hierarchies
Finding a User’s Forecast
32. Example: Factoring
Personas • Pain Points • Delivery • Right Doc • Style
Repeat sentence syntax to highlight new info
33. 5. Use friendly, accessible style
Personas • Pain Points • Delivery • Right Doc • Style
• Orient your reader to keep them focused.
• Use time words: now, later, before, first, start, finish
• Use place words and phrases: “Here’s what
you’ll see.”
• Use active and passive voices to emphasize user /
product interactions
34. 5. Use friendly, accessible style
Personas • Pain Points • Delivery • Right Doc • Style
• If you wouldn’t say it out loud, don’t write it
• Additionally
• Optionally
• Subsequently
35. 5. Use friendly, accessible style
Personas • Pain Points • Delivery • Right Doc • Style
• Use a positive, friendly tone (aka “Aloha Style”)
• Casual language, but no jargon
• Short sentences: “Here’s how.”
• Positive reinforcement: “It’s easy!”
• Contractions: “Now you’re done!”
36. And now we’re done…
… with the presentation.
Let’s move on to the exercises….
37. Exercises
With a partner or in a small group…
1. Think of a software product or tool you use, and
discuss yourself as a persona. Personas need:
• Name • Psychographic information
• Photo • Task flows and times spent
• Job and Career • Performance
• Demographic information measurements
(age, education, etc.) • Pain points
What relevant factor might a writer be
surprised to learn about you?
38. Exercises
2. Discuss a recent IFG™ situation
(for a product that has documentation).
• What was the problem you were trying to solve?
• Where did you start looking for answers or help?
• Where did you ultimately find it?
• Did it meet your needs?
• What message did it communicate about the
product?
• How could a professional writer have done
better?
40. Awesome!
Thanks so much!
Additional questions / comments?
Contact me any time: grebstock@salesforce.com
Twitter: @salesforcedocs
Editor's Notes
How can we learn from it?How can we simulate the reactive writer’s direct understanding of user problems?
MindshareUsershare
User BobHow do I reset my Salesforce password?Hard to read and understand, not formatted, some less than useful information
User FredCalls Amber at Salesforce supportShe writes a knowledge article
to the company/product/official product doc
Unflattering to the company/product/official product doc
Put out their hair fire.Retain and keep them coming back (maybe not right away)
Here’s the main meat of the presentation.
quantitative and qualitative
Let’s take a look at an example…
Our Sales Operations persona
Another example. Now we’re creating a single persona and addressing their interactions with a number of our products.Now let’s move on to talk about the second tactic: identifying potential pain points in our products.
I say “potential,” because when you’re first writing the doc, you don’t know for sure what’s going to cause confusion or problemsTalk about SF and three releases a year and how the org is upgraded automatically. Potential problems for both users and sysadmins.Once we’ve identified potential pain points, we need to find places to deliver doc and user assistance.
SpectrumUser isolationUser inclusion
Now let’s look at an exampleSpectrum
The native Salesforce Data.com product lets users find and add Data.comaccounts, contacts, and leads to salesforce.It also lets Salesforce users clean their records in salesforce to make sure their data is up to date with Data.com.We faced some challenges in helping users implement the product.
What kind of doc does th user need?A three-part solution to the problem
Marquee page! Shows where the value is in our product.We sent them directly to a conceptual topic, by name, so they would understand how to interpret this valuable data.Once you have your user in your help system, you can keep them there and make them more comfortable by making your style more accessible.
It’s your job to create meaning, not the reader’s job.Who is this information for? (identifying)What is this product/feature/concept/field? (concept, overview, reference)When does the user need to do this… care about this? (task, task of tasks, map)Where does the user start… go next? (overview or map)Why is this important to my user… does the feature do this? (overview or map)How does the user do this? (task of tasks or task)
Don’t need to doc something, don’t do it. Don’t need a topic intro, don’t write one. Don’t need a note, leave it out.Let your title do the heavy lifting, help users make a decision about reading it.It’s your job to figure out the use case.
It’s your job to create meaning, not the reader’s job.Frustrating error messagesIndulge yourself and be reassured that you’ve covered all the details, then streamline.
All levels: titles to body text to listsIt’s your job to create meaning, not the reader’s job.Pare down your languageMore factoring, less thinking!
Users internalize this syntax and anticipate the type of content they will find.
The Salesforce record was previously compared with…If you want to…The two records, the record, the record.
This is the same thing support reps do in conversation.So they will know what’s important
It’s your job to create meaning, not the reader’s job.Pare down your language
Jargon is alienating, but it seeps in very easily.