2.6 Connect with velcro, not cement

Updated on

Make sure you, your team and your users can pull apart your documentation to get right at the information they need.

Video: Don't do this to your customers

Have you ever been to Home Depot or Lowe’s and asked someone where a tool or part was? Which response did you prefer?

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

Video: How to connect your docs with velcro

Documentation that is attached with velcro can be easily pulled apart and combined together to meet different needs for different users. If you bunch all of your information into a single help page or a large PDF it becomes very hard to use in support situations.

Let's look at an example.

If you had a customer ask you "How do I update my email settings?" could you send them a url that points exactly to an article that answers their question? If you have to tell them to "look halfway down the page" then your docs are connected with cement.

We regularly respond to support questions with a single url that answers our customers' question. It is the single most effective way to manage your support requests and help your customers be successful.

If their question is more complex then we might send them 3 or 4 articles. Because each article addresses a specific answer we can easily piece them together to meet the individual needs of each customer.

Keys to connecting with velcro

In order to really connect your documentation with velcro you need to create and deliver documentation that meets the following criteria:

  1. Your documentation has to be on the web
  2. Each article needs to have a unique url (There are some really expensive help systems that don't do this. Avoid them like the plague.)
  3. Each article should answer one, and only one, question.
  4. Your support team needs a simple way to access the urls for these articles and paste them into emails, support chats and forums.

Start out right and you won't have a problem

If you follow our approach to writing documentation by answering questions and balancing scope and detail you won't have any problem with having documentation that is connected with cement.

If you already have a lot of documentation that has been attached with cement then tearing it apart can be a challenge. Our customers have told us that the simplest approach has been to start fresh and follow our methodology with new documentation. In a very short time they have a lot of documentation that is really useful to their users and their organization.

What does that mean? It means that if you have a bunch of documentation that stinks it is probably better to just start from scratch than to try to migrate it to a more effective delivery format.


Add your comment

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Previous Article 2.5 Use pictures
Next Article 2.7 Insert your docs where your users need them
Still Need Help? Contact Us