Helping Users in Need

Recently, a user sent an email to the KDE documentation list complaining that the KDE4 documentation left him in the cold after upgrading from KDE3.  This is something the Gnome documentation team needs to be careful with as we think about the Gnome3 help.  We’ll have a lot of Gnome2 users who are disoriented, and it’s our job to help them.

Brad Hards replied to the user, pointing out that KDE documentation is a volunteer effort, and asking the user to contribute something.  I am entirely sympathetic to this response.  I understand the difficulties of trying to produce good help with a skeleton crew of volunteers.  But from the perspective of actually helping the user, it’s a complete fail.  And at the end of the day, we do what we do to help users.

Here is how I think one should respond to a message like this:

1. Sincerely apologize to the user.  Don’t make excuses.  Don’t use volunteerism as an excuse.  If your apology starts with “I’m sorry, but”, you’re doing it wrong.
2. Identify exactly what problems the user is having and how the documentation could have helped the user.  Try to keep an open line of communication with the user.  Do not try to get the user to do work.  Just try to understand his problem better.
3. Write some documentation to help the user.  Don’t worry too much about getting it plugged into whatever documentation system you have.  Don’t worry too much about making it a final copy.  The goal is to have real instructional information that can be reviewed.  Use a wiki or your blog or whatever you find most convenient.
4. Ask the user to review what you’ve written.  You’re not asking the user to be a copy editor or a proofreader.  You’re asking him to tell you if this new documentation is helpful.
5. Revise.  Repeat.
6. When the new documentation works, make sure to put it through whatever quality control systems you have in place and to get it integrated into your documentation system.

Here’s what this accomplishes:  First and foremost, it actually helps the user.  It takes a disgruntled and frustrated user and turns him into a satisfied user.  With this kind of personal attention, it might even turn him into a downright happy user.  Second, because we’ve helped the user by writing real documentation, instead of answering questions on a mailing list, we’re helping countless other users who will never take the time to email us.

Finally, by giving the user something very concrete to do, we’ve given him a low-barrier entry point for contributing to our community.  Maybe he’ll stick around.  Or maybe he’ll go back to whatever he was doing, just a little happier.  I don’t know.  But what I do know is that “Find something to do and do it” is not a good way to get new contributors.  “Here is a simple task that is relevant to you personally” is far more effective.

♫NP: Fred’s Slacks Pt. 1 by Mingo Fishtrap