3

In writing procedural documentation, I have the choice of writing the complete step-by-step instructions with references to an appendix of illustrations,

For instance:

1. Do task 1 (see Fig. 1)
2. Do task 2 (see Fig. 2)

Illustrations
-------------
+-------+
| Fig 1 |
+-------+
+-------+
| Fig 2 |
+-------+

or to accompany each step with an illustration, almost as if the steps were the captions to the illustrations,

For instance:

+-------+
| Fig 1 |
+-------+
1. Do Task 1.

+-------+
| Fig 2 |
+-------+
2. Do Task 2.

Is there any research to show which method is more effective for the person attempting to learn the material? What are some of the considerations I need to make in choosing one method over the other?

If it makes any difference, each document is 10-15 pages long, about 25% of which is text and 75% is illustration.

1

1 Answer 1

3

First, ask yourself if all the illustrations are necessary (i.e. are these screen captures illustrating a screen with one button on them?).

The reader is going to be very annoyed having to flip back and forth between the procedure and the diagram. I don't have any links to show you for that, but I've done actual testing with users and the overwhelming result is to have the illustration in line with the procedure, even if that same illustration is duplicated in 15 different procedures.

If you are talking about software, however, it's a better practice to have information embedded in the software screen itself (either a tool tip or a pop up tutorial) than making the user look in the documentation for the information (because they won't).

EDIT: Maintaining that kind of documentation becomes a burden for the writer, especially if they have not placed the illustrations by reference and each has to be updated individually.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.