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.

Expand and collapse chapters in the sidebar

Now, by clicking on chapter titles in the right or left sidebar, readers can expand and collapse chapter contents while still viewing a lesson. This makes it much easier to find related lessons.

You can try it out for yourself in our example Salesforce manual.

You can also set a preference for how you would like to have chapters expanded when the page opens: no expansion, just expand the current chapter or expand all chapters.

Procedural Manuals

Some manuals are just a collection of articles. But some are designed to be followed in a step by step fashion from lesson to lesson. We call these tyes of manuals procedural manuals. You can now choose to mark manuals as procedural. Procedural manuals will have numbers prepended to the chapter and lesson name.

The impetus for this feature came from our ideas about roadmaps and roadblocks (read more about roadmaps and roadblocks). For a long time, ScreenSteps Live has been really good at removing roadblocks for users. We are now working on making it easier to provide roadmaps for your users. So, if you are creating a new user set up guide or an implementation guide we would suggest that you try out procedural manuals.

• Learn how to adjust chapter and procedural settings for your manuals

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.

In my opinion there is no such thing as good documentation that doesn’t have pictures.

It shouldn’t be controversial, but it is. Written words simply can’t communicate information as quickly and clearly as a screenshot can so if you are leaving out pictures you are killing the effectiveness of your documentation.

In this installment of our Docs That Rock Whiteboard Video Series I explain why in more detail:

Check out more “Docs that Rock” videos.

• 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.

Many companies of all types and sizes utilize the services of virtual assistants because it’s proven to be an effective and easy way of delegating tasks, and allows more time in your schedule to handle all of the other items on your constantly growing to-do list. However, there may be times in which your virtual assistant will need to be trained or briefed on an assignment request and it is at this time that visual items such as screenshots and images can make a major difference in the details.

It’s so tempting to just shoot off a quick email full of instructions, but sending your virtual assistant a quick explanation of a complicated duty can result in misinterpretation and frustration on both ends. For example, you may ask your assistant to complete a task using a specific software program that they are unfamiliar with, and they end up totally missing the mark with the task. Now, not only is the task incomplete, but you will have to take additional time to re-explain the task or complete the assignment yourself.

We have a lot of customers who use Clarify to work with their virtual assistants. By taking just a few minutes to capture screenshots and images of the program’s interface, they are able to help their assistant get a clear idea of what they need. Many of our customers tell us that using Clarify to create their instructions actually takes less time than writing out an email. The result is a better experience for both parties. Our customer has a fully completed task, their assistant is paid and they are both happy.

If you are currently working with a virtual assistant or are thinking about hiring one, be sure to try out Clarify. You won’t find a faster or simpler way of delivering clear instructions that don’t get misunderstood.

Stop losing time and money due to unclear instructions

Learn how »>

The more we talk to people the more we realize that they are trying to remove the frustration of being misunderstood. Haven’t we all been in these situations?

• We get work back from a developer or designer and its clear they didn’t understand what we wanted.
• We give instructions to an employee and it becomes clear there was a miscommunication.
• We try to help a customer or client and it’s clear they didn’t grasp what we were telling them.
• We explain problems to software vendors but from their response we can tell that they have no idea what we are talking about.
• We write down notes for ourselves only to be totally confused when we read them a week later.

Misunderstanding costs time, money and can be a huge cause of frustration. So if you are wondering when you should use Clarify, think about the times that you are misunderstood. Think of those times when you feel your temper rising because someone just doesn’t understand you.

That is when you should use Clarify.

Save Time. Reduce Frustration. Clarify Your Communications.

Download a FREE Trial >

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