Resources for Teaching Instructions
T. R. Girill
trgirill@acm.org (ver. 1)

Exercise Role (Topic) Science Applied Here Instructional Design Features Connections to Real Life

Ex. 0
plain0
annotated0 Guidelines for good instructions
(rules of thumb for all instruction cases) Patricia Wright:
Between-subjects studies show significantly more text revisions and more consistent revisions with overt guidelines.
These guidelines make text usability explicit for students. Introduces basic audience analysis and self-editing of instruction drafts. Regina Bailey:
Extracting DNA from human cheek cells nicely illustrates applying these guidelines (both positively and negatively).

Ex. 1
plain1
annotated1 Fully Worked Cases
Good instructions
(cooking new potatoes) Introduces kitchen recipes as a surrogate for laboratory or software instructions. Introduces the same text usability issues as instructions in industry but without any special vocabulary.

Ex. 2
plain2
annotated2 Poor instructions
(chili mac) Kalpana Shankar:
Ethnographic studies reveal the value of text revision even in biology lab notes. Builds text revision skills by externalizing how to detect and correct flawed instructions. Teaches editorial skills routinely used by working scientists and engineers.

Ex. 3
plain3
annotated3 Safety warnings
(microwave boiling water) Introduces the role and value of warnings within instructions. Shows risk management as a benefit of well-designed instructions.
Microwave kettle is example.

Ex. 4
plain4
annotated4 Scaffolded Cases
Two-stage editing
(cranberry sauce) Uses comparative word count as a simple usability metric. Introduces iterative (multi-stage) text revision with feedback on each stage. Shows the practical problems of omitted unit conversion.

Ex. 5
plain5
annotated5 Two-stage editing
(pancakes) Uses comparative word count as a simple usability metric (again). Introduces "cherry picking" of easy problems to disclose further, latent ones. Same as Ex. 2.

Ex. 6
plain6
annotated6 Discovering latent problems
(stuffed squash) Again practices iterative refinement (Ex. 4) by cherry picking easy problems first (Ex. 5). Same as Ex. 2.

Ex. 7
plain7
annotated7 Discovering latent problems
(butterscotch brownies) Same as Ex. 6.
For a similar, more abstract case, see Ex. 12. Same as Ex. 2.

Ex. 8
plain8
annotated8 Integrating Graphics with Text
Worked case, good art
(rubber cement) Edward Tufte:
Effective technical illustrations apply good human-factors engineering. Applies basic usability principles to technical art. A simple case that introduces the design issues posed by most real illustrated instructions.

Ex. 9
plain9
annotated9 Worked case, poor art
(irregular joint) Same as Ex. 8. Introduces the need to edit art along with technical text. Shows the practical problems of useless, irrelevant, or omitted technical illustrations.

Ex. 10
plain10
annotated10 Scaffolded unworked case
(oval template) Same as Ex. 8. Combines the need for risk warnings (Ex. 3) with the need for illustration editing (Ex. 9). Real-life instructions often have text, art, and risk/warning problems all at once.

Ex. 11
plain11
annotated11 Longer, More Complex Cases
Hidden problems
(mildew) Like Ex. 6 but offers longer, more complex practice. Long cases (11, 12, 13) show that the guidelines are robust, not limited to short, for-school cases only.

Ex. 12
plain12
annotated12 Hidden problems
(computer files) Like Ex. 7 but longer and more abstract. Long cases (11, 12, 13) show that the guidelines are robust, not limited to short, for-school cases only.

Ex. 13
plain13
annotated13 Hidden problems
(carpet wax) Again applies comparative word count (see Ex. 4 and 5). This case removes all of the scaffolds inserted to focus student attention in earlier cases. Long cases (11, 12, 13) show that the guidelines are robust, not limited to short, for-school cases only.

Ex. 15
plain15
annotated15 Taking notes to help plan, revise
(Internet fact checking) Michael Hoey:
Action-item matrix for taking notes on a process applies text-linguistics research to drafting instructions. Links structured notes to both revision and drafting, so bridges from earlier cases to Ex. 14.
Introduces an authoritative web reference portal (lii.org). Structured online fact checking supports both home medical and university research.

Ex. 14
plain14
annotated14 Instruction Drafting
Students draft text
(draw a spiral) Invites applying Ex. 15 text-linguistics techniques to this less structured case. Uses simple figures to prompt student drafting and revision.
Makes a good collaborative activity for small groups. Iteratively drafting and revising instructions based on trial runs is typical documentation practice.

Exercise	Role (Topic)	Science Applied Here	Instructional Design Features	Connections to Real Life
Ex. 0 plain0 annotated0	Guidelines for good instructions (rules of thumb for all instruction cases)	Patricia Wright: Between-subjects studies show significantly more text revisions and more consistent revisions with overt guidelines. These guidelines make text usability explicit for students.	Introduces basic audience analysis and self-editing of instruction drafts.	Regina Bailey: Extracting DNA from human cheek cells nicely illustrates applying these guidelines (both positively and negatively).
Ex. 1 plain1 annotated1	Fully Worked Cases Good instructions (cooking new potatoes)		Introduces kitchen recipes as a surrogate for laboratory or software instructions.	Introduces the same text usability issues as instructions in industry but without any special vocabulary.
Ex. 2 plain2 annotated2	Poor instructions (chili mac)	Kalpana Shankar: Ethnographic studies reveal the value of text revision even in biology lab notes.	Builds text revision skills by externalizing how to detect and correct flawed instructions.	Teaches editorial skills routinely used by working scientists and engineers.
Ex. 3 plain3 annotated3	Safety warnings (microwave boiling water)		Introduces the role and value of warnings within instructions.	Shows risk management as a benefit of well-designed instructions. Microwave kettle is example.
Ex. 4 plain4 annotated4	Scaffolded Cases Two-stage editing (cranberry sauce)	Uses comparative word count as a simple usability metric.	Introduces iterative (multi-stage) text revision with feedback on each stage.	Shows the practical problems of omitted unit conversion.
Ex. 5 plain5 annotated5	Two-stage editing (pancakes)	Uses comparative word count as a simple usability metric (again).	Introduces "cherry picking" of easy problems to disclose further, latent ones.	Same as Ex. 2.
Ex. 6 plain6 annotated6	Discovering latent problems (stuffed squash)		Again practices iterative refinement (Ex. 4) by cherry picking easy problems first (Ex. 5).	Same as Ex. 2.
Ex. 7 plain7 annotated7	Discovering latent problems (butterscotch brownies)		Same as Ex. 6. For a similar, more abstract case, see Ex. 12.	Same as Ex. 2.
Ex. 8 plain8 annotated8	Integrating Graphics with Text Worked case, good art (rubber cement)	Edward Tufte: Effective technical illustrations apply good human-factors engineering.	Applies basic usability principles to technical art.	A simple case that introduces the design issues posed by most real illustrated instructions.
Ex. 9 plain9 annotated9	Worked case, poor art (irregular joint)	Same as Ex. 8.	Introduces the need to edit art along with technical text.	Shows the practical problems of useless, irrelevant, or omitted technical illustrations.
Ex. 10 plain10 annotated10	Scaffolded unworked case (oval template)	Same as Ex. 8.	Combines the need for risk warnings (Ex. 3) with the need for illustration editing (Ex. 9).	Real-life instructions often have text, art, and risk/warning problems all at once.
Ex. 11 plain11 annotated11	Longer, More Complex Cases Hidden problems (mildew)		Like Ex. 6 but offers longer, more complex practice.	Long cases (11, 12, 13) show that the guidelines are robust, not limited to short, for-school cases only.
Ex. 12 plain12 annotated12	Hidden problems (computer files)		Like Ex. 7 but longer and more abstract.	Long cases (11, 12, 13) show that the guidelines are robust, not limited to short, for-school cases only.
Ex. 13 plain13 annotated13	Hidden problems (carpet wax)	Again applies comparative word count (see Ex. 4 and 5).	This case removes all of the scaffolds inserted to focus student attention in earlier cases.	Long cases (11, 12, 13) show that the guidelines are robust, not limited to short, for-school cases only.
Ex. 15 plain15 annotated15	Taking notes to help plan, revise (Internet fact checking)	Michael Hoey: Action-item matrix for taking notes on a process applies text-linguistics research to drafting instructions.	Links structured notes to both revision and drafting, so bridges from earlier cases to Ex. 14. Introduces an authoritative web reference portal (lii.org).	Structured online fact checking supports both home medical and university research.
Ex. 14 plain14 annotated14	Instruction Drafting Students draft text (draw a spiral)	Invites applying Ex. 15 text-linguistics techniques to this less structured case.	Uses simple figures to prompt student drafting and revision. Makes a good collaborative activity for small groups.	Iteratively drafting and revising instructions based on trial runs is typical documentation practice.