When describing how to write documentation in ScreenSteps Greg and I often tell people to create task-based lessons. You think of a task that the user needs to accomplish and you show them how to do it. I’ve been thinking about this lately and while accurate, I don’t think this description fully communicates how ScreenSteps should be used.

So here is another stab at it- Document the experience.

People should use ScreenSteps to create documentation centered around the experiences the user will have with the software. Imagine different scenarios that the user will find themselves in. What questions will they have? What will they want to do?

When you sit down to write documentation consider the following:

• What questions will the user ask the first time they launch the software?
• What tasks will the user want to accomplish with the software?
• What questions will the user ask the first time they use a particular feature?
  

If you begin your documentation with a list of questions that a user might ask then you can sit down and create lessons that respond to those questions. What ends up happening is that you write documentation that is really useful to the user because you are showing them how to get something done.

In addition, if you are a software developer you will find that by using this approach your application will go through a refining process. As you ask questions and document the software step-by-step you will find things that don’t quite work as they should or a workflow that could be improved.

Sometimes it seems like documentation authors believe they are getting paid by the word. You should focus on writing as little documentation as possible. With every word you add to you documentation you decrease the likelihood that someone will read it. Repeat this over and over to yourself as you write your documentation and the quality of your output will improve dramatically.

We personally believe that, in many cases, it is better to have less detailed documentation that is not technically “complete”. What do we mean by that? There may be something you are documenting that has one caveat that affects 1% of your users, another that affects 2%, etc. If you put all of those caveats in your documentation you create a cluttered mess.

You have therefore made you documentation useless for everyone.

What is the point in that? Write your documentation for 90% of your user base. Then create a separate section for those niche cases, a section that the 90% never need to see.

The next time you are writing a lesson or tutorial, try this technique. Pull out all of the caveats. Focus on making the documentation clear for the majority of your users. Your documentation will be easier to write and easier to read and will actually become useful.