Without clear goals your software documentation is bound to fail. Recently we have started thinking of our documentation in two contexts:
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.
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.
Road maps should be used for:
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.