Documenting a Form or Flow: Implications vs. Labels

form

Have you ever seen help for a form or wizard that tells you the obvious stuff but leaves out the important stuff?

For example:

Step 1: Put your email address in the Email Address area.

Step 2: Put your password in the Password area.

Step 3: If you want to save your password, check the Save Password box.

Etc.

This example shows two sides of the same problematic coin.

  • It gives unnecessary information.
  • It excludes good information.

Giving unnecessary information

Obviously, the reader knows what an email address is. If not, then “Step 1” isn’t going to help.

Unnecessary words on the page do these things:

  • Make the documentation less visually appealing
  • Make the documentation harder to read
  • Make the task harder to do (going back and forth from the screen to the doc)
  • Make the task seem more complicated than it really is.

In this case, if we want to help the reader along, we can say:

Fill in your details, then click OK.

(Note that I do like to say to click OK. “OK” in the real world doesn’t necessarily mean, “save my data.” But the words “email address” and “password” DO mean “email address” and “password,” no matter how computer-literate you are.)

Excluding good information

What kind of information could we give in those steps? Implications.

Readers don’t usually get confused about what to put in an on-screen field. They usually don’t get confused about how to choose an option (though sometimes they do).

But they do get confused about whether to choose an option. And this is where we can help.

Leaving aside the actual wording, the idea would be something like this:

Fill in your details, then click OK.

Save My Password: Check this box so that you don’t have to type your password every time you open the program. If you’re using a public computer, you might want to leave this box unchecked.

Describing implications often takes less room than describing labels, because you delete a bunch of worthless steps and replace them with one helpful sentence.

Then again, writing about implications takes more work and more thought (and sometimes it actually takes more space).

But it’s worth it:

  • You’re actually helping people.
  • You’re creating something that a trained monkey couldn’t create.

The monkeys may object, but your readers won’t.

Have I got all this wrong? Do you have a better way, or any other suggestions I’m forgetting? Let me know!

Tags:

2 Responses to “Documenting a Form or Flow: Implications vs. Labels”

  1. Hemal Patel
    June 4, 2013 at 9:40 am #

    So true.

  2. admin-Robert
    June 16, 2013 at 4:04 am #

    Thanks, Hemal! I’m glad I’m hitting the right notes.

Leave a Reply

Subscribe without commenting