The Art of the Start in Documentation and Demos

Two mistakes about how to start software documentation and demos, dissected.

Documentation

I was checking a knowledgebase article this week. I skimmed the instructions. It all seemed straightforward, I thought. The instructions were detailed, step-by-step, with screenshots.

Then I sat down, getting ready to follow the procedure. I saw the first screen, I recognized the first screen. I know I had seen it before. But where?

The step-by-step procedure was missing the first step.

I spent the next 5 to 10 minutes trying to click the write button to open the dialog window that I saw in the online help.

Take-away

When we write documentation we are often trying to help people locate an option. Make sure the entry point is clearly sign-posted.

Demos

I was giving a demo of a web application to an end-user who is not particularly tech savvy. This type of demo is outside my usual target audience. When I changed my presentation style I was careful to remove the tech jargon and come up with analogies to link to previous knowledge. I had paid siginification attention to flow and potential cognitive overload.

But we got stalled before we even got going.

The product I was demoing, a web application, runs in a browser. The person watching the demo couldn’t see it as a specific product, not in the same way someone more versed in web apps would see it. I had been focused on how it integrates with browsers and simplifies internet usage. But perhaps I had done that too well. The person couldn’t see the web app as something the company had done.

It was easily fixed. When I opened the web page again I literally took 15 seconds to say. This is the product, this is the interface, this is the browser extension. Don’t they all look similar?

Now the person saw it as a product.

Take-away

As we talk to people with fewer skills or less experience make sure to state the obvious at the beginning so they can enter the product with you. When we train on a software we are entering a virtual landscape.

It’s a training landscape where we trainers are guides familiar with the terrain. But if people have never seen this type of software before we need to treat it like a hotel we just checked into. The learners want to get a lay of the land first. They want to orientate themselves and explicitly name different aspects of the environment.

Oh there’s the pool. The restaurant bar is down that hallway.

How the idea of the start can be used in training

Scaffolding is when the trainer helps the learner achieve more than they could do alone by providing support. For online courses and documentation, the right amount of scaffolding might be the first step: showing people where to start.