One of the reasons that technical communicators ought to know the business processes of their users (or at least the reasons they’re using the product) is to generate effective examples in the documentation.

I’m thinking here of a couple of ways of providing examples: simple “for example, if you…” statements and full narratives involving fictional names, dates, and so on.

When I first started my current job, I had to provide instruction for some fairly complex procedures performed using the new software. I knew that examples for the most complicated ones would help the audience understand how to use the screens involved. I created an overarching scenario that, while unlikely, was possible. The unlikelihood made it hypothetical; the possibility made it relevant. However, I still wondered whether the unlikelihood would give the users pause, and the effect would be lost.

I can imagine a reader coming to this kind of statement: “For example, if you are climbing a tree upside down with grapes between your toes, you would…” The reader could well think, “I’d never do that,” and move on. So the example becomes useless.

Further, in a full narrative even labeled as a fictional scenario, the user could read, “Mr. Smith needs to gather a bushel of chicken feathers before the big meeting…” But the user thinks, “That never happens here,” and again, the illustration falls flat on its face.

In exploring some “what ifs” to provide appropriate help material, I asked an interaction designer about what would happen if a user performed certain actions that the software allowed. He explained that they wouldn’t do that in the business process, so it didn’t matter. Things don’t work the way I was thinking. Basically, some series of actions just don’t make sense in a given organization’s processes.

In some video tutorials, I used an existing group’s account in a test version of the application, but I changed the header to name a made-up, but comparable, entity. However, when reviewing the videos, someone involved in the business process noticed that the account numbers included a code for the real entity, not some fake code for a group that doesn’t exist. (I left it that way because it would have been too much nitpicky work to change the numbers, I thought.) She didn’t think it created a problem, but it illustrated to me how people can notice even minute details that are out of place.

Examples can be theoretically sound and work in the software, but given the business process, they just may not make sense. It may help to review your examples with a business analyst at least and with the actual audience if possible so that they are procedurally sound and don’t cause confusion instead of resolving it.

Related posts (auto-generated):

  1. "If an App Is Designed Well…"