The key to creating great docs is to abandon projects and instead establish a documentation process.

I explain the details of how you can accomplish this in the short video below. The tips I share in this video are what our most successful customers use to make software documentation a key part of their business strategy.

Free eBook: 5 Keys to Successful Documentation

Learn how to get better results out of your software documentation:

Download our free eBook »

Unfortunately it is all too common. How often do your update your docs? What if you GPS was only updated as often as your documentation?

Here are three simple tips for keeping your documentation up to date:

1. Make it simple to know when docs need updating (pictures really help)

If your documentation only has text it becomes really, really hard to figure out what needs updating. You literally have to read everything. But if your docs use a lot of screenshots then you can quickly scan the documentation to see what needs updating.

2. Remove the barriers to updating your docs

If you have cumbersome authoring or approval processes then your docs will stay out of date. Make sure that your authors can quickly get access to source material, especially the original images used for your screenshots. You should also make sure that your review processes are not overly draconian. The more barriers you can remove the better chance your docs will have of staying up to date.

3. Make sure your docs get used

This is the single best tip. If you and your customers are using your documentation on a regular basis then your docs will stay up to date. The best way to get your docs used is to include your documentation in the customer support process. Your customers will instantly tell you when something is out of date and you can get it taken care of right away.

How do you answer customer questions in 140 characters or less?

The answer is that sometimes you can’t. Some answers require more detail. The trick is to optimize your online content for Twitter support. All you need is a Twitter account and a willingness to rethink how you structure and deliver your online documentation.

Optimizing your responses for 140 characters

If customers are going to ask for support in 140 characters then you need to respond in 140 characters. Let’s say your customer asks, “How do I integrate my account with x service?” on Twitter. You obviously can’t explain every detail in 140 characters and responding across multiple tweets can get really tedious. That isn’t what Twitter is good at.

But Twitter is really good at sharing links. So, instead of trying to provide all of the details in your tweet you need to share a link to your online documentation that has the answer your customer needs. On Twitter you need to point customers to the answer they want instead of trying to write that answer in 140 characters or less.

Do your docs pass the Twitter test?

But this won’t work if your online documentation isn’t optimized for use on Twitter. How do your get your online documentation ready for Twitter? They key is to have many small help topics that focus on specific questions your customers have.

Take this test. Look at the last 20 or so questions you’ve received in your support queue. How many could you respond to with a single tweet? Your tweet should look something like this:

@customer Here is how you do that: http://link_to_your_answer_in_your_online_help_system

If you can’t respond with a link that points exactly to the answer your customer needs then your online documentation has failed the Twitter test. It doesn’t matter if the answer is in your documentation “somewhere”. If you can’t send a url that points exactly to that answer you fail the test.

Many organizations fail the Twitter test because they clump too many help topics onto a single help page. We call this connecting your documentation with cement. What you want to do is connect your documentation with velcro.

If you want to learn a little more about what it means to connect your docs with velcro so that they can easily be pulled apart then watch this video, “Connect Your Software Documentation with Velcro”.

Offering customer support on Twitter doesn’t have to be hard. If you take the time to organize your online documentation you will find that you will be able to quickly answer questions and thrill your customers.

Free eBook: 5 Keys to Successful Documentation

Learn how to get better results out of your software documentation:

Download our free eBook »

• The worker told you they “thought” it was somewhere around aisle 8.
• The worker escorted you to the exact location of the tool or part you needed.

Obviously we all prefer to be given the exact information we need, not just general directions of where to look. This is especially true of software documentation.

You need to optimize your software documentation so that you and your support team can deliver exactly the information your customers need, when and where they need it.

The best way to do that is to create documentation that is attached with velcro. In today’s Docs that Rock Whiteboard video I explain exactly what connecting your content with velcro means.

Oh the horror. What if your GPS treated you the same way?

Don’t attach your documentation with cement. Move your docs online and attach them with velcro so that you can easily pull out just the information your customer needs.

1. Documentation that provides a road map
2. Documentation that removes roadblocks

Roadmaps vs. Roadblocks

A Road map tells someone where to start and what steps to take to arrive at a desired destination.

A Roadblock is something that keeps someone from continuing on the path they are already traveling.

The main difference is that someone who has encountered a roadblock already knows where they want to go. They are just stuck and need help getting unstuck.

Someone who needs a road map doesn’t know where they are going yet. That is why they need the road map.

For example, a consultant setting up Salesforce in a new org who gets stuck with setting up single sign-on doesn’t need a road map. They know what they want to do. They just need documentation that helps them remove the roadblock that is preventing them getting single sign-on working.

But a brand new Salesforce admin probably needs a road map that will help them implement Salesforce correctly and achieve product adoption. Removing roadblocks won’t help them yet since they don’t even know which road to take.

Customer Support vs. Customer Success

Our popular Plan not to Plan methodology is ideal for removing roadblocks. Someone gets stuck, they ask you a question and you answer it with crystal clear instructions. The next time someone asks the same question you have a ready-made answer.

But what about that person who needs a road map? Their needs are very different. They know the outcome they want. But they have no clue how to get there. The Plan not to Plan methodology doesn’t meet the needs of these people because they don’t even know which road they should be on. In providing a road map you need to address broader topics and best practices as opposed to just how-to’s. This takes planning.

Were do Road maps and Roadblock apply

Road maps should be used for:

• New customer onboarding
• Establishing best practices
• New user onboarding (when a new user is added to a plan or an account)

The goal with road maps is to give your customer a clear understanding of how they should be using your application.

Roadblock removal comes into play after the customer has the road map. The purpose of roadblock removal is to decrease customer support requests and keep your users sailing through their daily workflow.

Providing road maps will allow customers to adopt best practices which will ensure customer success. Removing roadblocks will decrease customers support requests.

As you develop your documentation strategy you need to address both issues. In a future post we will explain how we are tackling this issue here at Blue Mango.

I replied, “I don’t think you can help with this. It’s kind of complicated.”

To which he replied, “That’s OK. I’m good at making things complicated.”

I certainly couldn’t argue with his logic. He was good at making things complicated.

You will probably find in life that there are many people that are good at making things complicated. Avoid them. Don’t listen to them. They are simply setting you up for failure.

When people ask me for suggestions on how to improve their software documentation I respond with pretty simple solutions. Depending on the audience I get two reactions:

• Organizations who are struggling with how to create their documentation instantly latch onto the simplicity of the concepts, implement them and see immediate results.
• “Professional” technical writers tell me that the approach is too simplistic and therefore can’t be effective. They need a framework that is more robust.

Robust is another word for complicated.

What is my simple approach? Customers have questions about how to do things with your software. Your documentation should answer those questions with clear, step-by-step guides with lots of pictures. That’s it. ScreenSteps makes creating documentation like this extremely simple.

If you want a framework that is more “robust” then you can probably find a consultant that will charge you a lot of money to complicate your life. Or you could just call my son. He’s good at making things complicated.

• Is your customer support group inundated with repetitive requests for the same information?
• Are your employees clamoring to find out the details of your company’s new policies?
• Do you need to efficiently and effectively train new clients on the use of your product?
• Do you need to train your employees on the technology products you use to run your business?

Managing knowledge bases without an easy way for groups of people to access them can suck productivity out of your business. If your customers and employees are constantly scrambling to find the information they need you need to consider the hidden power of an online manual.

Online manuals centralize all of your pertinent data for specific groups. Whether it is a customer support manual, an employee handbook, a research guide, a lesson plan, an employee hiring test or a product tutorial guide, online manuals can solve your problems of distributing information to a large or small audience.

Compare this to what a lot of organizations are doing – locking their knowledge in PDF and Word files. Capturing your organization’s knowledge in these formats makes that knowledge hard to access and hard to update.

But with online manuals you can provide the flexibility of instant access to the material your customers and employees need wherever they are and whenever they need it. If you have locked your knowledge in a PDF or Word file the user has to:

• Find the file (probably hidden on your intranet somewhere or on someone’s hard drive)
• Download it
• Start searching or navigating through it to find the information they need

The process is so painful that every business we talk to reports that almost no one in their organization reads the manuals they create as Word or PDF files. All that work waisted simply because the information is trapped in a document somewhere and not online.

Publishing new content to your knowledge base is an additional hidden benefit of using online manuals. If you have a new product to add to your tutorial guide or you have expanded your base of operations to include a new branch office, you can easily incorporate the new information into your online documentation.

And updates? Not a problem. Did you forget a step in your step-by-step online guide? You can easily update your guide information to clarify and improve your instructions. No more searching for the latest revision of the document or sending out emails to your entire company just so that they have the “latest” version of the PDF or Word file.

You can also make your online manuals more engaging. Adding many images to Word and PDF files can dramatically increase their size making it more difficult to deliver to users. But with online manuals you can easily add images to clarify your documentation (especially if you are using a tool like ScreenSteps Live.

Online manuals are powerful tools for communicating crucial information with your customers and employees. So if your manual is gathering dust as it sits locked in a PDF or Word file it’s time to move online. The ease of access, ease of use and increased productivity for you and your customers make it well worth the effort.

The biggest mistake we see companies making when authoring their documentation is misunderstanding the relationship between scope and detail in their help articles. The principle they are violating is the Goldilocks principle (part of our 5 keys to great software documentation). They either deliver too much information or not enough.

In today’s Docs that Rock Whiteboard video I discuss scope vs. detail in software documentation and how keeping these two concepts clear in your mind can help you write better docs that will help your users and drive product adoption.

If you want to see a funny example of dumping too much information on your customers then check out our Chatty GPS video.

By the way, we are going to be releasing a full series of Docs that Rock Whiteboard Videos over the next couple of months. These were inspired by SEOmoz’s Whiteboard Friday videos which, if you haven’t checked them out yet, are awesome.

If there are specific topics you would like us to cover in this series, please let us know in the comments.

We created this video to show what life would be like if GPS units treated us the same way. Enjoy!

Software documentation shouldn’t be permanent, forum posts should

Software documentation shouldn’t be permanent. It should change whenever your application changes. You need to think of your software documentation site as the authoritative source for how-to information on your product. That means, if a software documentation article is no longer valid for your product you need to delete it or update it.

Forums are for user discussion. They are a place where users can post questions or problems and where you or your user community can do your best to help them out. If you start using your forums for documentation it can become tricky to figure out what to do with old postings. Do you delete them? Do you update them? Do you go through all of the old postings and put a note that says “This discussion doesn’t apply to the latest version of our software?”

It’s a tricky situation for you as a company and even worse for your users. Many times, your older forum posts will rank higher in search rankings, especially if they had a lot of inbound links. So what happens when I go to Google to search for a resolution to the issue I am having? I get an outdated forum post as the top result. Not a good user experience.

How to get forums and software documentation to work together

Remember that your software documentation site should be the authoritative source for the “how-to” information about your product. Follow these steps to keep everything where it belongs.

1. Make sure you create software documentation articles that answer real user questions.
2. Make sure those articles can be easily referenced (they have a unique url that you can share somewhere).
3. When questions are posted in user forums answer with a reference to your software documentation article that answers the question.
4. If you don’t have an article that answers the question then create one.

Let’s look at an example.

A user comes to your forums and creates a post asking, “How do I integrate your product with WordPress?” You might be tempted to respond inline. Don’t. Go to your software documentation site. Do you have an article on integrating with WordPress? If so, add a link to it in your forum response. If not, then create one in your documentation site and add the link to the forum post.

Now, let’s fast forward 3 months. Your product has changed slightly and the method of integrating with WordPress has changed as well. All you need to do is update your software documentation article. Since the forum post points to that article, any future visitors will be linked to the current, correct information. They won’t be presented with outdated instructions that simply won’t work.

Caveat – Make Sure Your Software Documentation Doesn’t Stink

This only works if you have great software documentation. If you point users to documentation articles that are unfocussed or unclear you are just going to create more frustration. If you want some tips about how to structure your documentation in a way that will work effectively with user forums as well as other areas of the web (social media, etc.) then check out our eBook, “5 Keys to Successful Software Documentation”.

Summary

If you remember that software documentation is for authoritative answers and forums posts are for user assistance you will know where your content belongs. If you start pointing forum users back to specific articles in your documentation managing customer support will be easier and your customers will be happier.

Illuminate Education is one of those customers. They provide data applications to educational customers. Their primary mission is to help those educators make a positive difference in students’ lives.

We just published a case study on how Illuminate Education is using ScreenSteps Live to make their mission a reality. Their ScreenSteps Live site has moved well beyond just being a collection of software documentation articles. Illuminate Education uses ScreenSteps Live to achieve three goals:

1. Improve customer support by integrating ScreenSteps Live with their help ticketing system.
2. Reduce adoption costs for their new customers (very important with the current shrinkage in state budgets).
3. Drive customer success by expanding their use of ScreenSteps Live beyond just showing customers how to use their product into showing educators how to interpret and act on data to create meaningful outcomes in students’ lives.

We love this quote from Jenny Rankin, Chief Education and Research Officer for Illuminate Education:

“I honestly believe that our help system (ScreenSteps Live) is a big piece of how we ultimately help kids. The fact that documentation, something that is so often thought of as a peripheral feature, is able to take a center-stage role as one of the ways we are impacting kids is really amazing.”

Read the case study to learn more about how Illuminate Education is making an impact with ScreenSteps Live.

Here are some simple rules that we use.

Teaching Concepts or Introducing New Features? Use a Screencast

When you are explaining new concepts for new features a video is going to be your best tool. Why? It’s more engaging. Your viewer probably isn’t sure yet if the new feature or concept will matter to them. You want to have a more engaging presentation to help catch their attention. Also, video will allow for passive consumption. They can watch the video while doing other things. If something comes up in the video that grabs them they can then focus on that subject.

Teaching How-To’s? Screencasts or ScreenSteps

There are two different types of how-to’s: informational and instructional. Informational how-to’s are really advertising features. For this type of how-to follow the advice mentioned above – use a screencast.

Instructional how-to’s are mostly used in support situations. The viewer knows what they want to do but they don’t know how to do it. In this case engagement isn’t a concern because the viewer is highly motivated. Clarity and speed are more important. This is where ScreenSteps excels. So, if your audience knows what they want to do but not how to do it then use ScreenSteps. You can create the instructions in a fraction of the time (5 minutes as compared to an hour or more) and your viewer will be able to consume the information much more quickly than they could in a screencast.

ScreenSteps vs. Single Image Sharing (i.e. Skitch/SnagIt)

This one is simple. Do you need just one image to communicate your message? Then use Skitch/SnagIt. Need more than one? Use ScreenSteps.

If you just need to point out a design flaw on a web page then Skitch or SnagIt will work great. But if you are trying to point out a bug that requires several steps to reproduce or communicate a how-to then ScreenSteps will work better. Our ScreenSteps.me has become very popular with our users for submitting bug reports to vendors. They tell us that the vendors always thank them for the clarity of their reports and the “roundtrip” email communications are reduced since their initial report clearly identifies the problem.

Conclusion

All of these tools are communication tools. Not all communications have the same needs and goals. Look at what you are trying to communicate as well as the interest level and needs of your viewer. Then choose the tool that will get the job done most effectively in the least amount of time for that specific communication.

I read two articles recently. One article highlighted the technical communication work of a six-year-old while the other was by a professional journalist for a major online publication. One example communicated information clearly and concisely. The other talked in abstractions. Can you guess which was which?

Anne Gentle of Just Write Click showcased some technical communication work from her friend’s 6-year-old daughter. The aspiring instructional designer created a step-by-step guide showing how to create a Play-Doh apatosaurus. When you look at the results you might notice something – there are no words, just pictures.

Contrast that with this article by Tony Bradley at MacWorld, “Using Google Docs on the iPad”. In the article Tony Bradley describes in words what Google Docs looks and feels like on the iPad. Here is one excerpt:

The next screen took a little getting used. There is a small section toward the top for typing text, with a bar at the “bottom” that lists the currently logged-in Google account in the middle, with a Sign Out button on the left, and a Help button on the right. But the reason bottom is in quotations is that below this bar is a massive amount of unused space that takes up about two-thirds of the iPad display. I tried it in portrait and landscape—either way there is a huge section of useless space.

There isn’t a single picture in the article. Just text describing the Google Docs interface.

The question is, which author communicates more information in less time? Which author helps you understand more in less time? I think the 6-year-old is on to something. Anne comments in her article, “This elementary-school student definitely ‘gets’ that the future of tech comm is in pictures.”

Clearly somewhere between 6 years old and adulthood text becomes our primary mode of communication. This is because we all know that any educated person needs to know how to write. But communicating is far more important than writing and in many situations, especially in technical communications, words don’t communicate effectively. They are too abstract, too vague and too open to misinterpretation. A picture by a six-year-old will trump the best writing of any technical writer.

So at what stage in your life did you stop talking in pictures? When are you going to get started again?

Free eBook: 5 Keys to Successful Documentation

Learn how to get better results out of your software documentation:

Download our free eBook »