Tomorrow we will be hosting a new webinar that will be really valuable for those of you who have to communicate with users about products you create or support.

Our customers often ask us if they should use a screen recording application, like Screenflow or Camtasia, or something like ScreenSteps (ScreenSteps is a tool for creating step by step guides out of still images).

What they are really asking is “Should I create a video/screencast or a step by step visual guide (what we call a ScreenSteps document)?”

Our answer is, “It depends.”

The truth is, if you are going to have an effective product communication strategy, you need to be using both screencasts and ScreenSteps documents. The tool you use for a specific communication depends on two things:

• The level of engagement your target audience has with your product at the moment you are communicating with them.
• The type of knowledge you are trying to transfer to that user.

In tomorrow’s webinar we will layout a framework that will help you decide when to use a screencast and when to use a ScreenSteps document. We will follow a new user through four levels of engagement with a product and discuss what type of communication is most effective at each stage. We will also provide examples of effective communications at each stage.

The four stages of user engagement with a product are:

1. Product awareness
2. Product interest
3. Product investigation
4. Product implementation

This webinar will be ideal for marketing and product managers, IT and customer support or anyone who has to educate users on product usage.

Today’s software company, whether providing desktop or SAAS offerings, provides customer support in a number of different settings. For example, in our company we interact with our customers in five different ways:

• Email
• Forums
• Live on-line chat
• Twitter
• Telephone

All of these communication tools allow the person offering support to point customers to resources on the web that answer their questions. If your company has online help that is designed correctly then you will be able to leverage your materials in order to quickly answer customer questions.

Let’s look at five keys to making your online help documentation work for you when handling customer support requests.

1) Create short documents that demonstrate tasks

When you write your documentation you should show users how to perform tasks, not discuss features. For example, create a lesson that shows “How to configure an account” rather than “The account administration screen”. By creating short, task based documents you can point your customer directly to documentation that shows them how to do what they want to do. This removes the step translating the description of a feature into the necessary steps required to complete the task and reduces the amount of follow up questions.

Short, task-based lessons prove very helpful when providing support. When helping a customer in a support interaction you can string together multiple online help documents for the user to help them perform a larger task.

Look at the document titles in the image above. Notice how each title explains a task.

2) Make the URLs of each help document easily accessible

Whenever someone is viewing an article in your online help documentation they should be able to copy the URL from the browser address bar. If your online documentation delivery system uses frames that hide the actual URL or if you place multiple answers on a single page then you are making it more difficult to link to the content.

Customer support via Twitter pointing the user to specific document urls

3) Author content in a format that is easy to search

When looking for the relevant document to send to a customer you will probably need to search your documentation to get the URL. Make sure your documentation delivery system has search functionality that returns relevant results.

4) Use a publishing system that allows you to quickly add new content and update existing content

Documentation should be a process, not a project. Your documentation will need to be updated as new customer questions come in or your offering is updated. Whether or not your documentation keeps pace with these new needs will depend on how easy it is to update.

Make sure you use a publishing system that makes updating content as effortless as possible. If too much work is involved then your documentation will become stale as the more (seemingly) pressing matters of the day push documentation updates to the back of the line.

5) Create content in a format that is clear

It is important that you choose the proper format for your online help documentation. You don’t want your documentation to create more questions than it answers. Above all, your documentation needs to be easy to follow. We recommend using static screenshots and text as this provides the best balance of clarity, ability to search and ease with which you can keep your documentation up to date.

This documentation uses text and images to clearly outline the task to be performed

-

Your online help documentation can be a real asset for you regardless of which setting you are interacting with your customers in. By implementing these five keys to better online documentation you will get the most out of your documentation investment.

For an example of how we have implemented these keys in our own documentation take a look at our ScreenSteps manuals.

(more…)

This morning I read a post by Tom Johnson titled “If No One Reads the Manual, That’s Okay”. In it the author describes how he is writing a 200 page manual that no one will ever read and that somehow that is all right.

That no one will read a 200 page manual is perfectly OK. That people are still writing them is insane.

In the comments of the post, some technical writers were making the case that users needed to read the manual. But it doesn’t matter what you think users should do, only what they will do. The real problem here is that technical writers keep doing the same thing and expecting different results (the definition of insanity).

Here’s a suggestion, instead of talking about how people should use the content you create start trying to figure out why they aren’t using it.

And then fix it.

Don’t accept things the way they are.

Make your content useful and make it accessible when and where the user needs it.

Here are some questions to ask yourself (these all relate specifically to software manuals):

What happens when a user doesn’t read the manual? One of the things they do is contact support. Develop and deliver your documentation in a way that can be used in a support situation.

What are your users asking? Are they asking “Could I please have an overview of the Upload tab?” or “How do I upload a file?” Is your documentation structured around the questions your users have or the way your application is organized? Which would your user prefer? Which would be most useful to your users and your organization?

Where do users ask questions? They call, email, post to message boards and use Twitter. Can you deliver the content your users need (your manual) in the places where they are asking the questions?

These are the questions technical writers need to be asking themselves if they want to move beyond just fulfilling requirements to really adding value to their organizations.

Several months ago we recorded a webinar on this exact subject called Why Your Documentation Stinks and How to Fix It. Check it out if you want some new ideas on how to get people to read the documentation you write.

The other day I was watching my 5-year old complete a connect-the-dots page. I was amazed at how such a simple concept could turn just about anyone into a semi-functional artist. All he had to do was draw one line at a time between two numbers. At the end he had completed a drawing that would have been far beyond his ability had the dots not been there.

This is exactly how your documentation should be. Software is not art. It isn’t golf. It isn’t the violin. You shouldn’t need to work years and years to master it. There is a task. It needs to be done. People are going to use your software to do it. Does your documentation allow them to connect the dots?

Now imagine if my 5-year old sat down and saw “1,2,3,4,29″. Imagine that between 4 and 29 there are bunch of dots with no numbers on them. What would he do? He would be extremely frustrated. Which dot does he go to next?

You can find these “missing numbers” in documentation all of the time and it creates feelings of extreme angst and frustration – not exactly the experience you are trying to create for your users.

This happens most often when documentation focuses on features and not tasks. Are you telling your user what your program does or are you telling them how to do it?

Next time you are documenting something, ask yourself, am I numbering all of the dots? Are my users going to be able to connect those dots? If not then go back and tidy things up. Your users with thank you for it.

I don’t ever plan my documentation. I used to. But not anymore. It’s a waste of time. Maybe if I were on a documentation team and had 6 months to get the documentation ready then maybe I would plan. I could plan and then revise and then plan some more.

But I am not on a documentation team. I run a business. I am the web programmer, accountant, custodian, sales person, system admin and business development director. I don’t have time to plan my documentation.

So what have I done? I have planned not to plan. I have created a system for documentation that requires no planning at all AND creates documentation that is much more useful to our customers. It really is quite simple. Just follow these simple steps:

1. I write down the questions my customers have actually asked me.
2. I create lessons in ScreenSteps that answer those questions.
3. I post the answers as a manual to ScreenSteps Live. You can see an example here.
4. When a customer asks a question I do one of two things:

- If I have a lesson that answers their question I send it to them. - If I don’t, I create one, add it to the manual and send it to them. See here and here for two lessons I added to our manual this last week in response to customer questions.

This system has worked really well for me. I don’t end up writing content that won’t ever get used again, the lessons are very easy to update because they focus around a specifc task and I can quickly respond to customer questions.

Try it out. On your next documentation project, plan not to plan. Just answer the questions people are asking. You will find that your documentation will be easier to create and easier to use.

When describing how to write documentation in ScreenSteps Greg and I often tell people to create task-based lessons. You think of a task that the user needs to accomplish and you show them how to do it. I’ve been thinking about this lately and while accurate, I don’t think this description fully communicates how ScreenSteps should be used.

So here is another stab at it- Document the experience.

People should use ScreenSteps to create documentation centered around the experiences the user will have with the software. Imagine different scenarios that the user will find themselves in. What questions will they have? What will they want to do?

When you sit down to write documentation consider the following:

• What questions will the user ask the first time they launch the software?
• What tasks will the user want to accomplish with the software?
• What questions will the user ask the first time they use a particular feature?
  

If you begin your documentation with a list of questions that a user might ask then you can sit down and create lessons that respond to those questions. What ends up happening is that you write documentation that is really useful to the user because you are showing them how to get something done.

In addition, if you are a software developer you will find that by using this approach your application will go through a refining process. As you ask questions and document the software step-by-step you will find things that don’t quite work as they should or a workflow that could be improved.

Sometimes it seems like documentation authors believe they are getting paid by the word. You should focus on writing as little documentation as possible. With every word you add to you documentation you decrease the likelihood that someone will read it. Repeat this over and over to yourself as you write your documentation and the quality of your output will improve dramatically.

We personally believe that, in many cases, it is better to have less detailed documentation that is not technically “complete”. What do we mean by that? There may be something you are documenting that has one caveat that affects 1% of your users, another that affects 2%, etc. If you put all of those caveats in your documentation you create a cluttered mess.

You have therefore made you documentation useless for everyone.

What is the point in that? Write your documentation for 90% of your user base. Then create a separate section for those niche cases, a section that the 90% never need to see.

The next time you are writing a lesson or tutorial, try this technique. Pull out all of the caveats. Focus on making the documentation clear for the majority of your users. Your documentation will be easier to write and easier to read and will actually become useful.