Spring 2013 — UC Irvine — Information & Computer Science — ICS 139W — David G. Kay
Writing Instructions
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.
This assignment: Build some object using Tinkertoys, Lego, or some other system with more than one type of component that can be 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.
Then, write a manual that explains how to build your object. On Wednesday, April 10, you will bring the individual components of your object and three copies of your manual to section; then 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.
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. The focus of this assignment is prose, not pictures. You must do your job without any illustrations. This also means that 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:
• Wednesday, April 10—Bring to class the disassembled components of your object and
three copies of a good draft of your manual. As noted above, you
will build each other's objects in class, which we expect will generate
suggestions for improvements to your manual.
• Tuesday, April 16—A final revision of your manual is due at the beginning of class.
As always, all previous versions (including the three copies edited by
your classmates) should be included with your paper submission. In this
case, you must also turn in your disassembled components along with your
manual. It's a good idea to re-read the Writing Assignment Requirements
sheet before submitting each assignment.
Suggestions and hints: You may find it helpful to start your manual
with a list of the components, describing and defining them so 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 author any favors by simply saying, "Yeah, it looks okay." Don't be hesitant to say what you understood or what you didn't; just do it pleasantly, helpfully, and professionally.