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: 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: 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. -----