Technical Editing & Production



Design of Procedures


Why Do We Really Write Procedures

The Logical and Rhetorical Construction of Procedural Discourse

Picture Perfect-- Selecting Graphics for Instruction

Screen Captures in Software Documentation



An article idea sitting in my idea queue is to discuss the differences in the type of information required and how the communication needs are quite different between procedures, problem-solving, and information seeking (such as looking up health information). One problem I see is that too much of a technical writer's mental model is geared toward procedures, which causes problems with the other two. What are the problems & differences? How do they effect the quality of technical documents?

Note that the procedures, problem-solving, and information seeking are all different types of technical writing. They are not to be considered as different facets of one document.

weak answer The propensity toward writing procedures, according to Douglas R. Wieringa in his article Why Do We Really Write Procedures, is because writing procedures is easy. In many ways, writing procedures is an easy fallback for technical writers who often produce documents on information with which they are unfamiliar. The procedure may contain conceptual information or feedback on what successfully completing a step may look like, but they are directly related to the procedure. A potential problem may be the amount of conceptual information and feedback provided.


In the undergrad class, I spend lots of time telling the students to write procedures with two levels, so they can address different audience knowledge levels, such as:

6. Remove the border from the text box

a. Click on Format-Text box
b. Change the color from black to No line
c. Press OK

What's the advantage here? What are the potential problems? How does it support multiple audiences? How would graphics be integrated with this style of design?

weak answer Procedures help users complete a task. All users bring a different level of knowledge to procedures. Procedure writers need to make sure that they accommodate the varying levels of user knowledge. Writing procedures with two levels is a great idea, so the user with more knowledge can complete the task without reading the details and so the user with less knowledge can read the details to complete the task. For graphics, I think that screen shots showing an overview would work best for users. I would include cueing techniques to help certain users.


How many of you have followed a procedure and somewhere around step 12 found it didn't make sense. It was impossible to do the step 12 because the options/actions were not available. After much anguish, you finally find out that step 8 had not been done right, but it took until step 12 for that incorrect action to become critical. Why do procedure writers not work harder keep the users orientated? How much is the fault of the writer and how much is the fault of the designer? Why don't the procedure contains results after steps so you know if it completed correctly? How could you design a set of procedures which do support this action-result method?

weak answer Procedure writers may not work harder to keep users orientated because they make erroneous assumptions regarding the user's knowledge/ability when designing the procedures. A procedure writer can understand the procedure so well that they become removed from problems a typical user might encounter while following the procedure.

Thoughts to ponder


Here's some instructions for inflating a Macy's balloon. Garfield and Kermit. Are the effective, why or why not? What happens if you inflate the balloon out of order?



Design by Michael J. Albers Copyright 2012. All rights reserved.
Send me an email.