Teacher Notes on Instruction-Writing Exercises

Exercise 12: How to store and retrieve files

Goal:

To practice using almost all of the instruction-writing guidelines on one set of (rather abstract) draft instructions.

Strategy:

Exercise 12 is much like Exercises 6 and 7 in its demands, but the noncooking topic here is software documentation rather than cleaning instructions (as in Exercise 11). Students who handled the previous exercises well will find that Exercise 12 reveals how directly their editing skills transfer to writing software instructions, a vast and profitable industrial role. Students who struggled to master the previous exercises, however, may find the relative abstractness of Exercise 12 and its multiple intertwined problems confusing or frustrating. Hence this exercise makes a nice challenge for students comfortable with using the instruction-writing guidelines, but it is probably best skipped or handled as a teacher-mediated case by students still unconfident of their instruction editing skills. (The file-storage program used here strictly as an example is actually a customized UNIX software tool developed at Lawrence Livermore National Laboratory.)
STUDENT VERSION:
This is another scaffolded but unworked example.
ANNOTATED VERSION:
As with Exercises 6 and 7, this shows full problem analysis and overt proposed solutions added among the scaffolding along the right side (for easy comparison with each original step). You might well need to spell out the entire worked sequence overtly to overcome the extra burden of the more abstract topic here.

Case:

Student version:

(12) How to store and retrieve files

1. If you have a binary file,
   be sure to request BINARY mode
   after you start.----------------------PROBLEM:
                                         SOLUTION:

2. You can begin by running--------------PROBLEM:
   NFT, a program that                   SOLUTION:
   automatically opens a
   connection to storage.

3. The PUT command is one of
   over a dozen that NFT offers.---------PROBLEM:
   Store a file by typing                SOLUTION:
      put filename

4. Retrieve a stored file
   by typing
      get filename
   unless you already have a-------------PROBLEM:
   file by that name, in which           SOLUTION:
   case NFT will print the message
   "cannot clobber existing file."
   Then you have a choice of-------------PROBLEM:
   typing                                SOLUTION:
      clobber
   to allow overwriting or
      get filename newname
   to change the name of the
   retrieved file as it arrives.

5. End NFT
   by typing  quit

Annotated version:

(12) How to store and retrieve files

1. If you have a binary file,
   be sure to request BINARY mode
   after you start.----------------------PROBLEM: WRONG ORDER
                                         SOLUTION: move after step 2

2. You can begin by running--------------PROBLEM: NO OVERT COMMAND
   NFT, a program that                   SOLUTION: Run NFT, a program...
   automatically opens a
   connection to storage.

3. The PUT command is one of
   over a dozen that NFT offers.---------PROBLEM: IRRELEVANT TEXT
   Store a file by typing                SOLUTION: delete extra words--
      put filename                                 Store a file...

4. Retrieve a stored file
   by typing
      get filename
   unless you already have a-------------PROBLEM: TROUBLESHOOTING TIP
   file by that name, in which           SOLUTION: add a warning
   case NFT will print the message       (see next problem)
   "cannot clobber existing file."
   Then you have a choice of-------------PROBLEM: COMPLEX STEP
   typing                                SOLUTION: subdivide in warning--
      clobber                                      WARNING--NFT automatically
   to allow overwriting or                         prevents you from
      get filename newname                         writing over a file
   to change the name of the                       of the same name.
   retrieved file as it arrives.                   Either
                                                     (a) authorize the over-
5. End NFT                                               write by typing
   by typing  quit                                         clobber     or
                                                     (b) change the retrieved
                                                         file's name by
                                                         typing
                                                           get filename newname

Note:

This exercise most closely supports the following 1998 California English-Language Arts content standard(s).
Reading:
Grade 7--"Analyze text that uses the cause-and-effect organizational pattern" (p. 42).
Grade 9/10--"Critique the logic of functional documents by examining the sequence of information...in anticipation of possible reader misunderstandings" (p. 57).
Writing:
Grade 7--"Revise writing to improve organization and word choice after checking the logic of ideas..." (p. 44).
Grade 8--"Write technical documents...identify the sequence of activities needed to design a system, operate a tool..." (p. 51).