Spring 2013 — UC IrvineInformation & Computer ScienceICS 139WDavid G. Kay

Writing Instructions

He wins every hand who mingles profit with pleasure,
by delighting and instructing the reader at the same time.
—Horace (Epistles, book III (Ars Poetica), c. 8 BC)

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.

  1. Students should place their components and the three copies of their manual at the front of the room.

  2. Then each student should repeat the following three times:

    1. Take another student's components and a copy of the manual.

    2. Following the manual's instructions, assemble the components.

    3. As you work, mark on your copy of the manual any questions that you wish it had answered, any assumptions that you had to make, or any other aspects that were not clear.

    4. When you're finished, write on your copy "Assembled by" and your name.

    5. Then find the author, show him or her your product, and let the author make notes on any discrepancies between your assembly and what the author intended.

    6. Finally, return the pieces and the manual to the front of the room (where the remaining copies of the manual are).