In-context Procedural Instructions

People always have a lot to say when you tell them you write instructions, especially software instructions. And I always sympathize.

Last weekend, I elicited a group groan from some of my friends when I brought up the annoying fact that, in most software, if you try to follow along with the procedures, they disappear as soon as you click back on the application.

Tom Johnson’s post today on using graphics and screenshots highlights the user perspective on procedural documentation. Pitcures are more important than words.

Perhaps the problem isn’t that people need more pictures, it’s that they need procedural help to be more integrated into the task they are performing. 

Why would you open another window to show a picture of a screen that you already have open? It’s all so post-modern!

The latest version of Fullshot has a nice solution to this. Little callouts popup that point to the next button to click and guide you through the process of taking a screen capture.

When procedures appear one step at a time, there is only one step to read.

I think in the technical writing field there is a lot of questions about the utility of the work we do. In my opinion, a lot of that has to do with not what we write, but the way people get access it. 

When Words Lose Their Meaning

Structurally deficient. Functionally obsolete.

Which one of these words mean that a bridge will collapse?

In 2001, this is how the I35W bridge in Minneapolis was described by a technical writer.

Holly Harkness wrote a short post that points the finger at unresponsive politicians, but I think, as technical writers, we have to think about the effects of the language we use.

We are taught not to use jargon. But, as we regularly speak to people with extensive knowledge in a field and learn more about the subjects we document, we adopt the language of our industry.

We begin to speak, think and write like the people we were hired to translate into plain english.

In the least, this results in poor documentation. In the worst, people don’t understand the significance of a situation because the words we use diffuse the meaning of what we are trying to say.

I am not blaming the techncial writer for this tragedy. In cases like this there are major factors like millions of dollars in public money, law suits, politics and bureaucracy that add up to a collapsing bridge being described as “structurally deficient” and “functionally obsolete”.

I do think, as technical writers we have a responsibility to stand up for language and words and do our best to make sure that a collapsing bridge is described as what it is: a collapsing bridge.