Highlighting Action

When I was doing mostly writing, the usability engineer for my team told me to write all topics in such a way as to invite action. He said that the reader should come away knowing specifically how to implement the knowledge in the topic, and shouldn't just feel as though he or she now had a kind of understanding of the concepts behind it. That's an easy thing to do when the topic is focused on how to accomplish a task, but harder when the topic is there to give a background to a technology or feature.

I found writing these conceptual topics this way hard to do, I suppose because I was thinking more about providing complete information than about helping the reader accomplish a job. Now that I'm an editor, I can see it more easily—sometimes I'll read a topic and come away wondering how that information could be useful, instead of just perhaps interesting. When that happens, I go into the topic and look for the parts that imply action, or that the reader needs to act on to accomplish, or that provide choices to the reader. These are the things I ask the writer to highlight—all the other information should go at the end of the section or article, so that people who like to know the full story can read it, but people who are in the middle of a job can skip it until later.