ICS 139W Spring 2005
Writing Instructions
Introduction
Computer programmers write instructions for a living. But programming languages are simple and unambiguous, and computer processors interpret them more reliably than human beings interpret natural language instructions. Writing instructions for human execution, then, requires skills that programmers may not automatically possess.
The assignment
Build some object using Tinkertoys, Legos, or some other system with more than one type of component that can combined in more than one way. (Note that some small Lego kits do have just one "correct" assembly; such kits would not be suitable for this assignment.) You must be able to bring to class all the pieces necessary for assembling your object. Your object should consist of 20-30 pieces. As you build your object, maintain mental or written notes of the steps you follow.
Now that you've built your object, write a manual that explains how to build it. On Friday, April 15, you will bring the individual components of your object and three copies of your manual to class. Some of your classmates will try to follow your manual to build your object. At the same time, you will be following someone else's manual, so you will not be available to answer oral questions about your manual or your object — your classmates' success will depend entirely on your writing. The focus of this assignment is prose, not pictures; your manual should not have any pictures or diagrams. If specialized skills or complex tools are required to build your object, you should not assume that the reader will be familiar with them; they will need to be described in your manual.
There is no required length for this manual; take as much space as you need to get the job done, and no more. Similar assignments in the past have typically been four to five pages long. When you bring your components to class, you must be sure not to bring them in a package that shows the final product.
Due dates
| Date | What's due? |
| F 4/15 | Bring the following materials to class:
|
| M 4/18 | A final revision of your manual is due to be submitted via Checkmate by 1:50pm. Bring to class all previous versions (the three copies edited by your classmates), along with your bag of components. Again, be sure your bag contains a piece of paper with your name, so that we can easily identify that it's yours. It's a good idea to re-read the Writing Assignment Requirements page before submitting this assignment. |
Suggestions and hints
You may find it helpful to start your manual with a list of components, describing and defining them so that you can refer to them later. (Note how this mirrors the organization of many computer programs.)
Some objects are best described in terms of modules, giving the instructions for assembling each module separately, then explaining how to assemble the modules into the whole object. (Note again the close analogy with software.)
Organizational guides to the reader, such as section headings and a table of contents, may also help the user of your manual follow the instructions more easily. But include these only if they're truly helpful; anything can be overdone, and it's certainly possible to write a clear manual with paragraphs of prose and nothing more. (Interestingly, students in most Humanities writing classes are forbidden from using organizational aids like these, on the rationale that they make the writing job too easy by letting the writer avoid coming up with clear prose to mark the transitions between parts of the document.)
What to do when you get to class with your manual and your components
The first rule of reading someone else's work is to be both honest and kind. You don't do the authors any favors by simply saying, "Yeah, it looks okay." Don't hesitate to say what you understood and what you didn't; just do it pleasantly, helpfully, and professionally.