I recently blogged about how you can help users in need.  My advice was completely independant of what tools you use to write, build, and distribute your help.  Whether you do all your help in a wiki or have static HTML on the web that you keep in a version control system or install DocBook files along with your software, I think what I wrote is a good way to handle user problems.

But I think Mallard can substantially help you do this more efficiently.  Mallard takes a very flexible approach to topic-oriented help that allows you to write new content easily.  If you’re writing linear documentation in a format like DocBook, it can be difficult to start writing a solution to a problem without first going through the arduous task of figuring out how it fits into the navigational structure.

If you’re using Mallard, you can just write a stand-alone page and publish it for review.  I recommend first deciding what kind of content you’re writing.  Is it a set of steps to accomplish a task?  A solution to a common problem?  A conceptual overview?  A tip to help the user work smarter?

Mallard doesn’t enforce this content type like DITA does, but knowing what kind of content you’re writing allows you to work from standard templates, which should help you write more useful content.  By the way, I recommend all projects identify common content types and produce templates for them.  This is something we’ll be tackling in the Gnome documentation team soon, and I invite everybody to build on our work.

Once you know what you’re writing, and with template in hand, you can more easily get down to the business of turning thoughts into words.  You can convert your page to HTML without plugging it into a larger document so that your user can review it on its own.

Of course, you’ll still need to get it integrated into a document if you want it to be useful to others.  This isn’t necessarily trivial.  It could be that you can just plug it into an existing guide for common problems.  But you very well may need to rethink parts of your content organization.  Mallard makes content organization easier and more flexible, but there is still no substitute for human thought.

The real boon is that you can help and engage your user before you get bogged down in bookkeeping.  And that helps you create a more dynamic community that can more effectively help its users.

♫NP: Brown Skin by India.Arie

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