TITLE: User Documentation and Instructional Design
AUTHOR: Eugene Wallingford
DATE: December 21, 2006 2:49 PM
DESC:
-----
BODY:
Yesterday while clearing out some of the paper that has
built up in my office over the course of the semester,
I was reading through the conference copy of several
sets of OOPSLA tutorial notes. One that grabbed by
interest was from a tutorial that we had to cancel for
lack of registration, on how to write user guides and
tutorial documents. OOPSLA caters to software developers,
and we knew at the time we accepted this one that the
audience might be slim. But as I thought about the
notes I was sad that we didn't attract more of an audience
for this tutorial. It would have been useful to a lot
of folks.
I was struck by the fact that writers of documentation for
users face many of the same issues that teachers face.
The first part of the tutorial dealt with users and
learning: what they need to learn, and how they can learn
it. The writer needs to remember that the user doesn't
see the system in the same way as the developer, and may
in fact be a different sort of person entirely. This echoes
the recent "our students aren't like us" theme in several
of my posts. The tutorial then proceeds to give concrete
advice on the such topics as:
- the differences between learning by reading and
learning by doing
- the cognitive burden shouldered by learners
- the distinction between dedicates learners and
midtask learners
I think that I sometimes assume that my students will be
dedicated learners, focused on the ideas that I am trying
to convey, rather than midtask learners, focused on
getting something done. But I suspect that many students
do a lot of their learning just-in-time, while attempting
a programming assignment or homework problem. Midtask
learners approach the learning task differently than the
dedicated learner. In particular, they tend to look for
what they need right now and stop reading as soon as they
find it -- or realize that they won't! This makes brevity
and specificity important elements of user documentation.
They are just as important when writing instructions and
tutorials for students.
The tutorial goes on to give concrete advice and examples
on how to write instructions, how to induce rehearsal in
the learner, and how to organize presentation to avoid
overloading the learner. Almost every page of the notes
has something to use as I think about refining my spring
Programming Languages and Paradigms course. I've written
extensive lecture notes for this course, of which I'm
proud. But I think I'll use some of my prep time in the
coming term to apply the ideas from this tutorial to my
lectures. I can think of a couple ways to improve them:
- varying the strategies I use to invoke rehearsal
(zooming and out, changing modes of presentation,
and supporting a new assertion with what we just
learned)
- making sure that my instructions clearly communicate
their intention, endpoint, time frame, and possible
signs o success and failure.
I guess I am not surprised by the similarities among writing
user doc and writing for students (and teaching from that
writing), but it never occurred to me to mine the former
to help me improve the latter.
These tutorial notes were fun to read even without having
the presenter in the room. They were written well, spare
but engaging. That said, as with most printouts from
slide presentations, I would have learned a lot more by
having the writer tell the stories that were abstracted
into her slides. And I definitely would like to see the
examples that she had planned to distribute to illustrate
the ideas in the tutorial.
User documentation is certainly not the only other writing
form from which instructors can draw ideas and inspiration.
Nat Pryce recently wrote about the idea of using
the comic book as a form for end-user documentation,
and there may be something we instructors could learn from
comic book writers. Before you scoff, recall that the
U.S. 9/11 Commission Report
The Path to 9/11
was adapted into a highly-acclaimed
comic book.
(If I recall correctly, either artist Ernie Colon or writer
Sid Jacobson is from my adopted state of Iowa.)
I think the OOPSLA crowd missed a good opportunity to learn
from this tutorial. But there is one consolation... I believe
that the tutorial presenter is currently writing a book on this
topic. I'll definitely pick up a copy, and not because I plan
to write a lot of user documentation.
-----