The State of Help Documentation Today: Totally Unsexy

First, A Little Background

Like a lot of startups, Red Monocle started with a problem.  I was working on a small team of great programmers at Métier and we needed Knowledge Management (a group with numerous responsibilities) to update our end-user help documentation.  Unfortunately for us, there was only one person who knew how to use the outdated, bloated software we employed for this purpose—and she was on maternity leave.  I worked with the poor girl who got stuck with the unfortunate task of figuring out the software and updating the content, and the pain of that experience made me look around.  Surely there was something better!  I found a couple of great solutions for large enterprises with dedicated technical-writing teams and deep pockets, as well as a lot of hard to use knock-offs that tried to copy those same features.

After some soul searching I decided to build something that would work great for us (and hopefully lots of other software teams).  I was really excited about building a kick-ass help documentation tool—but, as I shared my plans with people around me, I discovered something terrible:  everyone thinks that help documentation is boring!

Bummer.  Let’s take a look at why people think that help documentation is so unsexy.

Why Doesn’t Anyone Like Help?

I’m sure you have your own ideas (I’d love to hear about them in the comments), but this is my personal list:

  1. It doesn’t exist
  2. If it does, it doesn’t answer your question
  3. If it does, you can’t find the answer anyway
  4. Even if you find it, the answer’s usually out of date
  5. Even if you can navigate it and it is helpful, the interface is usually pretty ugly (and hasn’t changed in the past ten years)
  6. You usually don’t bother looking for it and just try to figure out the problem yourself

Okay, that’s fair.  But somebody out there is doing a good job of documentation, right?  Absolutely!

Sexy Help Documentation

Help Documentation Can be Easy to Find

This often-missed step is critical!  Google’s AdWords application does a great job of this.  It’s easy to find in search:

And you can’t miss it in the application itself:  there’s a link at the top next to the logged-in user’s name, and a huge sidebar on the lower left with frequently-asked questions.

Help Documentation Can Be Accurate

It’s a fact of life that your software will change after you’ve written the documentation and updates will be necessary.  How do you know if your help is out of date?  One approach is to survey your customers.  I don’t see this technique used a lot, but I do think that a simple, low-friction way to get input from your users is a great way to keep on top of your documentation shortcomings.  This example from Microsoft could be slimmed down quit a bit but it does give uses the opportunity to contribute:

Help Documentation Can Be Beautiful

Clean, modern, and easy-to-scan help documentation from Fetch.  Yes, please!

Help Documentation Can Be Right Where You Need It

Inline help is becoming more and more prevalent, thank goodness!  Here’s a beautiful example from Twitter:

The Good News

So we know that good documentation exists—now we just need to turn the tide against all the bad documentation out there.  I like to compare help documentation to the early years of JavaScript:  for a while, it had a reputation as the job that no one wants.  But eventually everyone will realize that help documentation is awesome for end users, and the internet will be a better place if we can just figure out how to solve the ugly problems.  It’s not going to be easy, but it will be worth it!