The Step-by-Step Plan to Creating Help for your Application

The need to create application Help is nearly ubiquitous – every app needs it – but there isn’t a lot of information available for people who are tackling the job for the first time.  I’m hoping to fill that gap.  This article is about creating Help when it’s not your job, when you’re not exactly sure what Help is, and when you need to figure it all out right now.

Author’s Note: This post is about online Help.  If you need a simple document to distribute to users try this free user guide template.

What exactly is Help?

Help is any method that enables users to answer their own questions.  Unlike support phone calls and emails, Help can be very low-cost because you don’t have to invest time into each individual question that your users have.

There are several types of Help:

  1. Static content, like printed manuals and PDFs
  2. Online content
  3. User-supported communities

Each of these types have pros and cons associated with them (more details below).

The Plan

Now that you have a clear idea of what Help is let’s discuss how you can actually make it.  This is a straightforward process:

  1. Identify your goals and special requirements
  2. Create a content strategy
  3. Pick a tool

Identify Your Goals and Special Requirements

You’ll want to put some thought into what your goals are for your Help.  An easy answer is “reduce support costs.”  What about driving deeper engagement?  Educating users on the topics surrounding your software?  Inspiring a community of die-hard fans?

While you’re thinking about goals you should also consider any special requirements.  These can be:

  • Available in 5 different languages
  • Pixel-perfect printing, to be bound and distributed to users
  • Available offline (such as by a downloadable PDF or a distributed CD-ROM)
  • Searchable
  • Support for images & videos
  • User editable (like wikis)
  • Integration with related products, such as Help Desk and Chat

Making a list of these features now will help you to develop your content strategy and to compare the various tools available to create the Help.

Develop a Content Strategy

Most products are too complex to just start typing stuff.  You need a plan for how you’ll tackle (and possibly delegate) the creation of the content.   Generally, you can organize by features, by task, or both.  Then you should consider the content style your Help should have.

Organizing by Feature

Facebook is a good example of organizing Help by feature.  The author took a look at the Facebook application, broke it into various sections (such as Timeline and News Feed), and then wrote Help content for each feature.  This is a good approach if your users tend to think of the features in the same way you do.  It’s not a good approach otherwise.  For example, if users tended to think of the News Feed as their Home Page, then they’re going to be confused and frustrated when trying to find the relevant section in the Help.  Notice that Facebook mitigates this a bit by calling the section “News Feed (Home)”.

Organizing by Task

Most users won’t read through your Help before using your application.  Generally, they’ll only open Help when they have a very specific problem or question, and they want answers as quickly as possible.  Organizing by task will help them find their answers quickly.

Gmail is a good example of this – the author put the most common tasks first and foremost on the page, organizing them in a way that the content is very quick to scan.

Combining Feature and Task

Combining the two approaches gets you the best of both worlds.  Users who like a bit of an education before using an application or feature can get the thorough content they desire, and users with specific questions can find answers quickly.

MailChimp has a good approach to this – note the sections for ‘Frequently Asked Questions’ and ‘Explore the Knowledge Base’.  By the way, Knowledge Base is just another way to say Help.

Identify and Articulate the Content Style

Users who look at Help will sometimes be frustrated, sometimes be looking for the answer to a specific question, and sometimes be looking for a general overview to get them started.  But they will always be in a hurry.  Curling up in bed with a software manual and a glass of wine is so incredibly rare that you might as well assume it’s non-existent.  Ensure the user a frictionless experience by writing a style guide for your Help now, before you write a single word.  This will ensure that the various sections of the Help are consistent in style and tone, so users will know what to expect as they explore.  It’s doesn’t have to be long or complicated.  Here’s an example:

Each page in Help will be no longer than 500 words.  Use of headings in varying font-size and weight will help the user skim content, as well as numbered lists and bullet points when appropriate.  In general, pages should include an ‘overview’ paragraph at the top to help the user understand the value to be gained by using the feature being described, then sections for the individual tasks that a user may accomplish with the feature.  Each task section should be “how to” guides that offer explicit, step-by-step directions and include lots of application screenshots.

Pick a Tool

Armed with your goals,  special requirements, and content strategy, you are now ready to start looking at your tool options.  Let’s look again at the three types of Help: static content, online content, and user-supported communities.

Static content


Static content are things like printed manuals or content loaded onto CD-ROMs.  They’re hard to change so they don’t change often.  This can be a good choice if your users like to access Help printed or offline.  They’re not a good choice if you update your content often – probably more than a couple of times a year.  Tools that create this kind of help are called Help Authoring Tools.  Wikipedia has a good list of the tools in this category if you’re ready to start comparing them.

Many Help Authoring Tools can generate your content in both static and online format.  This means you just have to write the content once, and then you can both load the content onto a CD-ROM and make it available online via a web browser.  Be sure to look at samples of the online content a tool creates when researching it – you don’t want to find after purchase that you don’t like its appearance and that it’s difficult to change.

Online content

Online content has all the advantages of websites, blogs, and web apps: rich content, instant availability, and searchability.  All of the examples in the ‘Develop a Content Strategy’ section are Online content.  Online Help content is created by a tool (sometimes called a Help Authoring Tool), and published for users to see.

One of the biggest advantages to online content is that it’s very easy to update.  You can even update the content more frequently than the product itself.  Say, for example, that your team had to release a new feature very quickly, and you didn’t have time to update the Help.  With static Help content you would have to wait until the next product release to update the Help.  With online content you can update it the next day.

Some tools support both static content and online content, and those are usually called help authoring tools.  Most of these tools don’t actually put the content online for you though – they create files that your web browser can display (HTML) but you have to work with the programmers or IT to get the files onto a server where your user can access them.  A few tools will put the content online instantly – Convey is one such tool.

User-supported comunities

Many people consider this the holy grail of Help – users ask the questions, users answer the questions, and you don’t have to do anything!  Unfortunately, these communities can be difficult to setup.  You need a lot of passionate users who like to assist other users.  Here are some questions to help determine if a user-supported community would work for your product:

  • Do you have enough users?
  • Will enough of them check every day to see if other users have questions?
  • Will they respond courteously and accurately?

Most companies find that they have to spent time monitoring the communities and answering user questions, so it’s not quite self-serve.

There are a couple of types of tools that create user-supported communities, including forums and Q&A sites.  Both types suffer from a major usability problem: it’s difficult for users to find answers to their questions.  That’s why you often see the same question asked over and over again.  So while this type of Help sounds perfect it has its drawbacks.  If possible, review the user-supported communities of products that you use personally and think about whether the format would work well for your product.

Popular tools that create user-supported communities include Get Satisfaction (easy to setup, paid plans) and phpBB (hard to setup, free).

Next Steps

So you’ve got your plan – identify your goals and special requirements, create a content strategy, and pick a tool.  If you’ve done this before and have feedback on the plan let us know in the comments.  Or if you have questions feel free to post them, and I’ll do my best to help!