Category Archives: TechLit Handbook

Teacher Notes on Description Writing

Guidelines for Writing Good Descriptions

Context for this case:


Other versions:

Introduce these guidelines by “touring” them with CDC’s Sudden Unexplained Infant Death reporting form.
Cognitive Apprenticeship
Features:

  • “Reveals the magic” behind effective technical descriptions.
  • Connects writing to authentic, nonschool reader needs.

 

Guidelines
for Writing Good Descriptions

Organization

  • OVERVIEW. Begin with a brief overview that reveals the object’s
    (a) overall framework, arrangement, or shape, and
    (b) purpose or function.
  • PARTS. Divide the object into parts and describe each part
    (a) in enough detail to use, make, or draw it, and
    (b) in a way that reveals its role, its relation to other parts.
  • ORDER. Organize the part descriptions to help your reader:
    (a) spatial order (top to bottom, outside to inside), or
    (b) priority order (most to least important), or
    (c) chronological order (order of [dis]assembly).

Content

  • SPECIFICS.
    • Include relevant specific features (such as size, shape, color, material, technical names).
    • Omit irrelevant background, confusing details, and needless words.
  • COMPARISON. Compare features or parts with other things already familiar.
  • CONTRAST. Contrast properties with different ones to reveal their significance.

Signals for Your Reader

  • FORMAT. Clarify your text with:
    • Heads. Identify topics with clear, nested section headings.
    • Lists. Itemize related features with indenting and marks.
    • Figures. Integrate figures and text with labels and references.
  • VERBAL CUES. Guide your reader’s expectations with:
    • Parallelism. Use parallel words and phrases for parallel ideas.
    • Proleptics. Use verbal links (also, but, however, etc.) to signal how your description fits together.

Three Roles for These Guidelines

    1. Audience analysis.
      The guidelines introduce the importance of writing for and helping an audience that depends on what you say. This concept will be new to many students, who expect to write only for their teacher. Reviewing the guidelines points out that technical texts (including descriptions of technically complex things) have real readers, and that those readers need the writer’s help to understand the thing described.
    2. Writing for a Purpose.
      While students can quickly see that people write and read instructions to help them carry out a (complex) task, they may need help seeing why people write and read carefully crafted technical descriptions.

      1. The Tour.
        One way to reveal the purpose of good descriptions is to tour the description-writing guidelines and give a brief, concrete example of each principle applied. Pointing out the different result of honoring or ignoring each principle, one by one with a simple case, shows just how well-designed descriptions are useful in ways that poor descriptions are not. See the “Giving a Guideline Tour” section below for an easy, systematic way to do this with a slight “crime scene” flavor that interests students.
      2. The Trial Run.
        Give every student a 3-by-5 card marked in some odd way (with a stamp or sticker). Tell the students to imagine the entire contents of their classroom jumbled into a pile of debris by an earthquake or tornado. Suppose that recovering from the rubble that one specifically marked card now in their hand was crucial (for solving a crime or rescuing missing people, for example). How could they describe in words that unique physical thing so that searchers who had never seen it could reliably find it (and distinguish it from all other debris) amid the jumbled classroom contents?
    3. Repair Techniques.
      The guidelines provide students with an overt, shared repertoire of techniques for repairing the flaws that they find in descriptions (from themselves or from others). The guidelines offer goals to strive for in good descriptions, and ways to improve weak descriptive passages. Finally, the guidelines are a kind of loaned experience: they make explicit for beginners what working professional writers and scientists know implicitly through long practice (thus they promote cognitive apprenticeship).

    Giving a Guideline Tour

    An easy, focused way to introduce each of these guidelines to students is to “tour” through them using some authentic technical descriptions to illustrate how they work. Sudden unexplained infant death (SUID) is a practical situation where real-life reporting (description) forms are not only available to the public but eagerly shared to promote their wider use. Hence, I have found that SUID forms from the U.S. Centers for Disease Control and Prevention (freely posted–scroll to page 16-at http://www.cdc.gov/mmwr/PDF/rr/rr4510.pdf ) provide a dramatic way to introduce the good-description guidelines to otherwise disinterested high-school students.

    The six-page SUID “investigation report form” at the above URL contains many clever descriptive features. First, it includes a concrete example of virtually every technique listed on the basic guidelines for good descriptions above. Surveying the SUID form is a convenient, persuasive way to highlight those techniques.

    Second, the SUID form is heavily scaffolded (with checklists, labeled tables to fill in, and prompted comparisons). Yet this exposure of often-hidden descriptive moves is very much “for life,” not just for school. At the sometimes chaotic death scene, first responders who witness possibly crucial details (about temperature, ventilation, or clothing, for example) need clear, organized prompts to help them record diverse nutritional, medical, and environmental clues in reliable ways. Months later and thousands of miles away (at CDC in Atlanta), investigators need systematic, easily compared reports rich enough in detail to suggest possible causes. The scaffolding on the SUID form helps both groups meet their needs in complementary ways. This is also a keen lesson for students in the social value of good technical description, for writers and readers alike.

    Third, CDC’s SUID form includes front and side infant-body outlines on which paramedics can mark wounds or scars. Many technical descriptions blend words and pictures, so this offers a practical introduction to the general design challenges of effective text-graphics integration.

    Finally, this real-life SUID form has its share of little imperfections that students can be asked to find and improve by using the guidelines (it needs a better way than a small empty box, for instance, to capture information about prescription and OTC medications that the infant was taking). So it also affords a nice opportunity to explore the benefits of guideline-based text revision. The usability features make this case a very helpful instructional tool.

    Comparison with Darlene Smith-Worthington

    Several items in the guidelines here overlap with those that Darlene Smith-Worthington includes in her Technical Communication: Writing Descriptions (Perfection Learning, 1997, 32 pp.), a short high-school technical writing text. Smith-Worthington approaches description writing quite broadly. She spends time on general audience analysis, on “observing things,” and on literary terminology (simile contrasted with metaphor and analogy, for example). Her guidelines for writing and revising descriptions are helpful, but they appear only late in her text (pp. 16 and 24, the last half of the book). Several extended example descriptions treat familiar but mechanically complex objects (a rotary egg beater, a clothes hanger) and could support much more commentary than they receive. One strength of her book is her use of nutrition labels and similar tabular product specifications, which she cleverly contrasts with descriptions in sentence and paragraph format.

    My approach to teaching technical description places greater stress than Smith-Worthington does on the psychological and linguistic techniques that make good descriptions good. I follow the same empirical, research-based approach to teaching technical writing that the American Federation of Teachers promotes for effectively teaching reading (summarized in Louisa C. Moats, Teaching Reading IS Rocket Science, Washington, D.C.: American Federation of Teachers, 1999, 32 pp., available free online). The last 30 years have revealed much about the psychological grounds for nonfiction text usability; we should not ignore these discoveries when introducing students to effective drafting and revising techniques.

    I also introduce description-writing guidelines before, not after, the text activities to which they apply. And I suggest explicitly invoking them in every subsequent lesson. They offer an easy way to review at the start of each lesson, an overt focus for practice, and a shared evaluation standard.

    Guideline Commentary by Patricia Wright

    Influential cognitive psychologist Patricia Wright evaluated the helpfulness of guidelines in “Chapter 4: Editing Policies and Procedures,” pp. 63-96, in Thomas Duffy and Robert Waller (Eds.), Designing Usable Texts (Academic Press, 1985). Wright explored experimentally whether people who have difficulty editing (including self-editing) lack relevant knowledge or lack the ability to apply the knowledge that they have (80). She performed a between-subjects experiment in which several dozen people edited a 340-word passage with many known flaws. One group used only general directions, while the second used six-point overt guidelines for how to edit (81). Those with the guidelines made almost twice as many editorial corrections (8.8 versus 4.5, a statistically significant difference) and were much more consistent (showed more intereditor agreement) about which features to change (82). Wright could not conclude whether it was lack of knowledge or failure to apply it that the guidelines addressed (84), but she noted that “editing skills seem very malleable” (83). Guidelines are no magic bullet, but they do seem to promote just the kind of behavior (more attention to text, more ideas for improvements, more agreement about what to improve) that underperforming student writers need. So I recommend guidelines as a reliable instructional aid.


    Contact: T.R. Girill trgirill@acm.org

Teacher Notes on Instruction Writing

Guidelines for Writing Good Instructions

Context for this case:


Other versions:

 

Introduce these guidelines by “touring” them with DNA-extraction instructions.

Guidelines for Writing Good Instructions

Organization

 

 

 

  • Are the steps presented in the order in which they are performed?
  • Is the first step really the first task that someone in the audience needs to do?
  • Should a long or complex step be broken into smaller parts?
  • Are all hidden steps made explicit?

 

Clarity

 

  • Is each step written as an overt command (beginning with an action verb)?
  • Are all steps easy to find and visually distinct?
    • List format?
    • Bullets or numbers needed?
  • Is each step precise and complete enough to be followed?
    • Includes needed details?
    • Excludes irrelevant text?
  • Are common problems covered?
    • Safety/danger warnings?
    • Troubleshooting tips?

Three Roles for These Guidelines

  1. Audience analysis.
    The guidelines introduce the importance of writing for and helping an audience that depends on what you say. This concept will be new to many students, who expect to write only for their teacher. Reviewing the guidelines points out that technical texts (and especially instructions) have real readers, that the readers need the writer’s help to do something, and that just what the writer says can make a big difference in how helpful the instructions are.
  2. Reading Critically.
    The guidelines help students learn to read critically by focusing their attention on the specific features “at work” in real-life instructions. Instructions are seldom drafted optimally the first time, so reading instructions critically (other people’s and one’s own as well) is crucial for good editing and self-editing. The guidelines are a slightly formulaic but psychologically well grounded look inside instructions to see what makes them helpful or unhelpful for the readers that depend on them.
  3. Repair Techniques.
    The guidelines provide students with an overt, shared repertoire of techniques for repairing the flaws that they find in instructions. The guidelines offer goals to strive for in good instructions, and ways to improve every weak step found. Finally, the guidelines are a kind of loaned experience: they make explicit for beginners what working professional writers know implicitly through long practice.

Giving a Guideline Tour

An easy, focused way to introduce each of these guidelines to students is to “tour” through them using some authentic laboratory instructions to illustrate how they work. For example, Regina Bailey’s 8-step process for extracting DNA from human cheek cells, posted at http://iblog.dearbornschools.org/wachholz/wp-content/uploads/sites/1032/2017/02/extracting-dna-from-cheek-cells-1.doc does this job nicely. Many alternatives exist (some sets are really teacher instructions rather than for students, however), but Bailey’s instructions are realistic yet simple enough to be workable in one period with only ordinary supplies. They provide great guideline cases:

  • Every Bailey step really is a command, with the verb first to make clear what action to take next (some have descriptive prefaces, which you can point out).
  • The separate steps are clearly marked, even sequentially numbered.
  • The steps include relevant detail needed to perform them, without irrelevant distraction.
  • Some list items combine several steps, providing the opportunity for students to reorganize or simplify them for clarity.

I always introduce instruction-writing guidelines before, not after, the exercises to which they apply. And I suggest explicitly invoking them in every subsequent lesson. They tie the separate exercises together: an easy way to review at the start of each lesson, an overt focus for practice, and a shared evaluation standard. I have even hung the guidelines in the classroom as a 3-by-4-foot poster to provide visual continuity and a tangible resource for student writers.

Guideline Commentary by Patricia Wright

Influential cognitive psychologist Patricia Wright evaluated the helpfulness of guidelines in “Chapter 4: Editing Policies and Procedures,” pp. 63-96, in Thomas Duffy and Robert Waller (Eds.), Designing Usable Texts (Academic Press, 1985). Wright explored experimentally whether people who have difficulty editing (including self-editing) lack relevant knowledge or lack the ability to apply the knowledge that they have (80). She performed a between-subjects experiment in which several dozen people edited a 340-word passage with many known flaws. One group used only general directions, while the second used six-point overt guidelines for how to edit (81). Those with the guidelines made almost twice as many editorial corrections (8.8 versus 4.5, a statistically significant difference) and were much more consistent (showed more intereditor agreement) about which features to change (82). Wright could not conclude whether it was lack of knowledge or failure to apply it that the guidelines addressed (84), but she noted that “editing skills seem very malleable” (83). Guidelines are no magic bullet, but they do seem to promote just the kind of behavior (more attention to text, more ideas for improvements, more agreement about what to improve) that underperforming student writers need. So I recommend guidelines as a reliable instructional aid.

Contact: T. R. Girill, trgirill@acm.org

Usability: How Technical Writing Succeeds

T. R. Girill
trgirill@acm.org
Technical Literacy Project
April, 2015 (ver. 3)

Handbook Table of Contents
Common Core Relevance

What is Usability?

Usability is a strange word but an increasingly influential idea. Any product designed for a specific purpose (such as tools, home appliances, or computer software) can be judged for success by its usability. For some people, improving a product’s usabilty is a full-time job. In 2007, Barbara Whitaker featured usability professionals in her New York Times employment column (Whitaker, 2007), where she passed along this explanation of their work from Microsoft’s Eric Danas:

We bridge the gap between what [any] technology is capable of doing and what users want to achieve.

A dozen different international engineering standards now endorse, describe, or apply usability for diverse industries. Most often cited is ISO9241-11, Ergonomic Requirements for Office Work with Video Terminals (ISO, 1996). This document inelegantly but clearly reveals the responsibilities of designers and the benefits to product users that usability imposes:

…[usability is] the extent to which a product can be used by specified users to achieve specified goals with effectiveness, efficiency, and satisfaction in a specified context of use.

Breadth of Importance

The diversity of professions concerned with usability revealsthe breadth of its importance.Among the endorsing organizations and websites are:

  • User Experience Professionals Association (uxpa.org)
    This cross-disciplinary group of “human factors” experts ranges from linguists to librarians and from anthropologists to engineers. The common interest that unites such different people is in empirical evidence about what technology users need and want, along with what design techniques most reliably meet those needs and wants. Besides its website, UXPA also supports an annual conference and the Journal of Usability Studies.
  • Usability.gov
    This informative website is sponsored by the U.S. Department of Health and Human Services. Perhaps surprisingly, it focuses not on the usability of medical tools or services but rather on how to design government agency websites for effective information delivery.
  • World Usability Day (www.worldusabilityday.org)
    The goal of this annual event is “to ensure that the services and products important to life are easier to access and simplier to use.” Software developers (and computer science undergraduates) are always major players. But the topical theme in 2007 was actually the usability of health care resources.
  • HCI Bib (www.hcibib.org)
    Human-computer interaction (HCI) is a chronic concern for usability professionals because much hardware and software is needlessly hard to use well. This website offers a 39,000-item bibliography, with every citation annotated and categorized, on the physical, psychological, and social aspects of improving computer interfaces.

Usability’s Complexity

Usability is complex in a very distinctive way: it is multi-dimensional. Several largely independent (although sometimes casually confused) strands comprise it.

Barbara Mirel devoted a whole book (Mirel, 2004) to explaining why

  • usefulness (enabling user-relevant tasks), and
  • convenience (easy exercise of available features)

are not the same. Both are necessary for product usability but neither alone is sufficient (and neither one entails the other). The international standard quoted above (ISO9241-11) already suggested that usabilty was threefold, requiring

  • effectiveness (achieving intended goals, Mirel’s usefulness),
  • efficiency (performing with economy and grace), and
  • satisfaction (meeting user expectations, matching user skills or limitations well).

Other engineers have characterized these three dimensions of usability somewhat differently, or have suggested even more independent strands, such as

  • learnability (important if new users are common),
  • memorabilty (if the gaps between use are often long), or
  • adaptability (if the tool or product should handle diverse situations).

This is not the place to referee alternative technical breakdowns of usability into its independent dimensions. Rather, we bring up its multi-dimensionality here for a special reason: to apply it to the usability of text.

Text Usability

Usability is an important property of nonfiction, nonnarrative text, just as it is of consumer products, software, or medical devices. The readers of technical text are also users:

  • They have goals or tasks in whose context they consult the text.
  • They judge the text (as they would any tool) by how well it helps them achieve those goals or tasks.
    • Do instructions (e.g., for extracting DNA from cheek cells) help get the job done?
    • Do descriptions (e.g., of bone fracture mechanisms) promote better understanding and far-transfer use of information?

Text usability has always been a background concern for writers and readers of technical prose. The computer boom of the 1970s, however, brought it to the foreground. For example, IBM was so often criticized for its unhelpful computer documentation that the company chartered a group of engineers at its Santa Teresa (California) Laboratory to explore how to improve IBM technical publications. The result was a 27-page internal booklet called Ease of Use (Ease of Use Study Group, 1979), which concluded that:

  • IBM software was often useless without adequate explanatory publications.
  • Publication “ease of use” in turn had three independent and vital aspects (p. 2). Technical information must be:
    • Easy to understand,
    • Easy to find, and
    • Task sufficient.
  • This was best achieved by pointing out these key text features to everyone who worked on IBM documentation and by deploying human editors who revised draft text with these three ease-of-use factors in mind.

Cultivating such technical ease of use might seem obvious until one compares this text design strategy with the advice often found in technical writing books of the same period. For instance, consider Henreitta Tichy’s Effective Writing for Engineers, Managers, Scientists (first edition 1966, second edition 1988). This was a very influential work, widely used in professional development courses for chemists or engineers. Yet despite ‘effective’ in its title, this book never mentions usability (or ease of use) in its detailed index. Tichy’s very typical stress was on sentence-level style improvements (grammar and word choice). The book largely ignores “task analysis” and hence improving a technical text by overtly pursuing the three dimensions of usability championed above by the ease-of-use engineers.

Text usability’s more recent influence shows in a different professional reference work that appeared a decade after Tichy’s second edition, namely Developing Quality Technical Information (by Gretchen Hargis in 1998, third edition by Michelle Carey in 2014). Although this work has a general, comprehensive title, it focuses largely on computer (software) documentation. This is perhaps unsurprising because it was copublished by IBM (along with Prentice Hall, later with Pearson). The 1979 ease-of-use themes shape all the topics and examples throughout this book. Indeed, ‘ease of use’ has replaced ‘task sufficiency’ as the label for the third essential usability (or quality) feature here. At 311 pages (587 in the third edition), this treatment is more than 10 times longer than IBM’s pioneering pamphlet, but it stresses quite the same view that usability is the proper measure of success for all technical text.

Text Usability and Teaching

Several science teachers have successfully experimented with helping their students communicate better by trying various text-usability guidelines or checklists…but always indirectly and never by name. In one case, P.K. Rangachari and Sheela Mierson “developed a [one-page] checklist and used it to teach critical analysis of published articles” (Rangachari, 1995, p. S21) to college juniors in an undergraduate pharmacology course. In another case, physiologists Douglas Seals and Hirofumi Tanaka (2000) constructed a five-page, heavily annotated “manuscript review” checklist. Their goal was to offer their students a tool for “developing [the] challenging but essential professional skill” (p. 53) of effective text revision. Both of these cases implicitly exposed science students to text usability issues. But both focused exclusively on the formal features of professional journal articles and both assumed collegiate levels of disciplinary background knowledge.

For high-school students, however, overt text usability work can easily address much more basic skills applicable to a much broader range of science communication situations. Explicitly introducing students to usability when you teach technical writing helps them in two ways:

  • Exposing this as a writing goal is part of “revealing the magic” behind crafting helpful nonfiction nonnarrative text, a teaching strategy more fully explained in the cognitive apprenticeship section. Students can only draft or revise toward (more) usable prose if they are aware of what this aim means in specific detail.
  • Usability talk provides a practical vocabulary for “metacognitive discourse,” for students evaluating the adequacy of their own text and that of others. Educator Mike Sharples has noted (Sharples, 1999) that most adults simply lack any vocabulary for discussing their own (nonfiction) writing strengths and weaknesses.

This diagram visually reveals the three dimensions, or independent aspects, of basic text usability, in the long “ease of use” tradition summarized above:

Usability diagram

Easy to Understand

This is the most familiar usability aspect by far. Everyone has experienced struggling with technical prose that they couldn’t understand (including students with inappropriate textbooks). To be understandable, text must be:

  1. Clear.
    Words or phrases that could easily mean different things to different readers (ambiguity) or that don’t seem to have any clear meaning (vagueness) make text needlessly confusing for everyone and impossible for ESL readers.
  2. Concrete.
    Technical text often discusses abstract topics (sometimes by means of mathematical expressions). But even such passages can be made more understandable with the help of realistic cases, models, analogies, or tangible examples.
  3. Well Styled.
    This may seem like a literary issue encroaching on science prose. Actually, however, there are fairly simple heuristics (rules of thumb) for improving the style of technical text (see Bennett and Gorovitz, 1997; for example, prefer shorter Anglo-Saxon words to longer Latin-based ones when possible). And scientists who read English-language articles but who work primarily in another language complain often about the hurdles that careless styling imposes on their understanding (e.g., Montesi and Urdiciain, 2005).

Relevant

Writers sometimes forget that even if a passage is easy to understand, it is of little use to readers for which the content is irrelevant. Usable technical text anticipates the information needs (both scope and level) of the likely audience (a good cake recipe won’t help those who want to cook a chicken). To be relevant for readers, text must be:

  1. Task Oriented.
    Most people read technical prose with an eye toward some planned future activity (perhaps specific and physical, like operating a fork lift; perhaps general and cognitive, like designing their next research experiment). Text oriented to the prerequisites, demands, and sequences of their likely tasks is more helpful than text that ignores those tasks.
  2. Accurate.
    Readers who rely on text for factual information expect tested procedures and reliable scientific claims and relationships.
  3. Complete.
    Balance is the key to usable completeness. Omitting needed steps or vital connections makes text unhelpful, even dangerous. Yet smothering those steps or connections in a flood of overwhelming or confusing detail undermines usabilty in another way. Relevant text omits nothing needed without including distracting stray information.

Easy to Find

This is the most overlooked aspect of text usabilty, and novice writers often neglect it. Yet even highly relevant text that is easy to understand is useless without effective access features. Accessibility really is a third, independent dimension of usability for science prose. Easy to find text has three characteristics (which, when they perform well, often don’t call attention to themselves):

  1. Organized.
    Text structure is important even in story telling. For nonfiction nonnarrative text the structure may be less familiar to some readers (a problem-solution sequence or a hierarchy, for example), but revealing it is crucial for reader success. All writing involves planning, and for technical text planning the structure is as important as planning the content.
  2. Retrievable.
    Good text structure helps readers only if they become aware of it through navigation aids planned and installed by the writer (or by a subsequent editor). To help readers find relevant parts of a long or complex text, writers need to pay attention to:
  • the signals that they provide.
    Parallel, overt lists of related items are one familiar text signal. Hierarchical section headings and subheadings are another. (These never appear in novels because findabilty is not a goal of novelists nor a concern for most novel readers.)
  • the chunk size of their passages.
    Long blocks of undivided content can make retrieving specific answers to specific questions difficult.
  • their access vocabulary.
    Besides the words within the normal text, writers must also consider supporting alternative, synonymous terms in indexes or other look-up aids.
  • Visually Effective.
    Technical text often looks quite different than most prose fiction or even most newspaper stories (Bernhardt, 1986). Including appropriate pictures, drawings (e.g., of equipment), or data graphs is one aspect of making science prose visually effective. Integrating the text and graphics so that they truly complement each other’s information delivery (with callouts and captions, for instance) is vital too. And managing data density using visual features to make text data rich without overwhelming readers is a constant challenge (e.g., see Tufte, 1983).

The Distance Comparison

Being easy to find and easy to understand (the presentation features) are important aspects of nonfiction text usability, but they play a different role than relevance (the content feature). You may help student writers balance their priorities among the three dimensions of usability by offering a comparison with distance.

In a 2013 post about “a new theory of elite performance,” psychologist Christine Carter approvingly quotes colleague Angela Duckworth’s revealing comparison of distance and achievement.

Duckworth starts with the familiar fact that

distance = speed x time.

From this equation it follows that even if speed is very low, with enough time one can still go any distance…as long as speed is not zero. That alone prevents time from helping one accumulate distance.

Likewise in general, psychologist Duckworth argues,

achievement = skill x effort,

from which it follows that even if skill is fairly small, with enough effort one can still compensate and reach significant levels of achievement…as long as skill is not zero. According to Carter, “researchers across diverse fields have produced remarkably consistent findings that back up Duckworth’s [multiplicative] theory.” (So there is empirical evidence that the tortoise’s approach to winning (long) races against hares really works.)

For science communication purposes, we are interested in one specific type of achievement, namely the value of technical text for an intended audience. In this case the formula becomes:

	audience  =  relevant  x  presentation
        value	     content      quality

With strong parallels to the two “distance” formulas above, this implies that even if relevant content (in a student’s draft text) is modest but not zero, presentation quality (understandability plus findability) will amplify its value for the audience (make it more usable). But where content is completely missing (or irrelevant to audience tasks or needs) then presentation quality, no matter how high, cannot rescue the text. (Scored sample short-answer nonfiction essays on Common Core tests, such as those in New York, illustrate exactly this formula.)

Hence, this prioritized approach to text usability prepares students well for writing outside of school, where presentation quality really amplifies relevant technical content but it cannot compensate for irrelevant (or absent) content.

Achieving Text Usability by Revision

In life beyond school, many people who write about science and technology increase the usability of their text iteratively, by repeatedly revising a quick draft to improve its usability features. This approach illustrates the benefits of viewing nonfiction writing as “text engineering.”

As influential software engineer Frederick P. Brooks has pointed out (Brooks, 2010), early in the 20th century engineers often planned a device, then implemented their plan, then revised the prototype repeatedly themselves:

Edison fabricated working versions of all his inventions in his laboratory. Henry Ford made his own car. Wilbur and Orville Wright built their airplane with their own hands. [p. 176]

By filling all three roles–planner, implementer, tester–they were able to gradually discover ways to make their inventions more effective and more usable, ways that they could not have foreseen at the start.

Now, in the 21st century, many engineers can no longer fill all three roles personally because hardware implementation and testing today often call for special skills and equipment. But with (most) software, this feedback loop remains possible, and technical writing is much like software design. Your students can often achieve (improved) text usability iteratively, just like software engineers. They can plan and quickly draft “prototype” text, which they then repeatedly review, revise, and test on others to find and fix its usability weaknesses.

A Conceptual Framework

The enduring value of three-factor usability as a conceptual framework for all students learning to design effective nonfiction text was reiterated once again in 2015 when influential communication consultant Janice Redish was asked to condense her 40 years of experience into a sentence of advice. Her reply:

You communicate successfully only when the people who need your communication
[1] can find what they need,
[2] understand what they find, and
[3] act appropriately based on their understanding–in the time and effort that they think it is worth (Oswal, 2015, p. 89).

References

Bennett, Jonathan and Gorovitz, Samuel. (1997).
Improving academic writing. Teaching Philosophy, 20(2), 105-120.
Berhardt, Stephen. (1986).
Seeing the text. College Composition and Communication, 37(1), 66-78, reprinted in ACM Journal of Computer Documentation, 16(3), 3-16 (1992).
Brooks, Frederick P. (2010).
The Design of Design. Boston: Pearson Education, Inc.
Carey, Michelle, et al. (2014).
Developing Quality Technical Information. New York: IBM and Pearson.
Ease-of-use Study Group. (1979).
Ease of Use. San Jose, CA: IBM Santa Teresa Laboratory.
ISO. (1996).>
Ergonomic Requirements for Office Work with Video Terminals. Geneva, Switzerland: International Standards Organization.
Mirel, Barbara. (2004).
Interaction Design for Complex Problem Solving. San Francisco: Morgan Kaufmann.
Montesi, Michela and Urdiciain, Blanca. (2005).
Abstracts: problems classified from the user perspective. Journal of Information Science, 31(8), 515-526.
Oswal, Sushil. (2015).
Conversation on usability. Communication Design Quarterly3(2), 63-92.
Rangachari, P.K. and Mierson, Sheela. (1995).
A checklist to help students analyze published articles in basic medical science. Advances in Physiology Education, 13(1), 21-25.
Seals, Douglas and Tanaka, Hirofumi. (2000).
Manuscript peer review. Advances in Physiology Education, 23(1), 52-58.
Sharples, Mike. (1999).
How We Write. London: Routledge.
Tichy, Henrietta. (1966, 1988).
Effective Writing for Engineers, Managers, Scientists. New York: John Wiley.
Tufte, Edward. (1983).
The Visual Display of Quantitative Information. Cheshire, CT: Graphics Press.
Whitaker, Barbara. (2007).
Technology’s untanglers: they make it really work. New York Times, July 8, 2007. Available online at: http://www.nytimes.com/2007/07/08/business/yourmoney/08starts.html

Text Engineering

T. R. Girill
trgirill@acm.org
Technical Literacy Project
October, 2018 (ver. 3)

Handbook Table of Contents

Thematic Introduction

Three Writing Challenges

Nonfiction (technical) writers–including your students–face three strategic challenges that are cognitively demanding (and often confusing):

  • Planning their text,
  • Analyzing their audience to meet its needs, and
  • Revising their draft for iterative improvement.

These tasks sometimes interact (plans affect drafts, but drafts can provoke a change in plans too), adding to the intellectual burden. And until recently, these tasks were usually posed to students only in literary terms–story structure, authorial stance, “writerly” style, etc.–which often proved unhelpful, mysterious, even intimidating. Now, however, many K-12 students meet engineering in middle or high school, perhaps through Project Lead The Way or similar curricular packages. Engineering design briefs involve clarifying project goals and user (audience) constraints, while optimizing a prototype calls for iterative revision. Hence, engineering offers a very effective alternative way to explain, coach, and practice all three “hard” aspects of nonfiction writing.   If your students are still unfamiliar with “human-centered” engineering design, the University of Washington’s Engineering School offers a basic but insightful five-facet tour specifically aimed at teenagers: http://depts.washington.edu/designme/human-centered-design-2/human-centered-design

Software engineering provides especially direct and helpful parallels to technical writing. Among the most basic and most useful for inexperienced writers is the distinction between coding and design (and hence between coding problems and design problems).

Coding vs. Design

V. Anton Spraul’s 2012 book Think Like a Programmer nicely explains this helpful distinction. Coding problems, which often result from “coding too quickly or without enough preparation,” tend to be local and small scale, like omitting needed parentheses or confusing the assignment (=) and equality (==) operators. A corresponding writing problem would be wrong spelling or an accidental subject-verb disagreement (e.g., “The team of players move quickly…” because ‘players’ is mistaken for ‘team’ as the subject of the sentence). Successful writers need to find and fix such coding problems, but that seldom improves the meaning or content of their text.

Design problems, on the other hand, tend to be global and large scale. They often involve meaning-altering omissions or confusions. For example, a program may be needlessly convoluted, with too many steps (just as a draft text can have too many parts or stray details). Or a program may omit needed features or fail to scale up (and hence run too slowly) for large data sets (just as draft instructions might need added enabling details or a draft description might need better text-graphics integration to explain something intricate or to work well for an international audience).

Engineers gradually learn to distinguish between coding and design problems in their software, addressing each in its appropriate way. Likewise, inexperienced writers grow more effective by learning to manage their textual micro-problems and macro-problems with different intellectual responses. The following sections explore the three big writing challenges (planning, audience awareness, revision) from this text-engineering perspective, teasing out the ways that writers can benefit from the insights of successful engineers.

Planning Programs Is Like Planning Text

The Text-Planning Challenge

Planning nonfiction text (before one starts generating sentences) can be daunting because it is really a twofold task. First, writers must plan their content–often posed as their “ideas” but better thought of as their textual assertions or claims. Second, they must plan their text’s structure along with the rhetorical moves (lists, headings, etc.) that signal the chosen structure to their readers. And sometimes content and structure interact, making text planning even harder (should I present my evidence for A by comparing it with B, or would that comparison only confuse the case?).

Planning, drafting, and revising are all cognitively demanding, so effective writers generally pull them apart (in time) to reduce cognitive load. And most teach themselves planning techniques or mental tools to further reduce that load. Unfortunately, traditional “literary” planning tools sometimes turn out to be lightweight or even frustrating–content-oriented tools like word maps often ignore structure, while structure-oriented tools like outlines often ignore content.

The Engineering Design Alternative

Fortunately, another approach to text planning is available. Taking a cue from the Next Generation Science Standards with their focus on actual science/engineering practices, we find that planning is a key feature of every engineering design. The Project Lead The Way (PLTW) K-12 curriculum, for example, embodies this for students in the “design brief,” where engineering students spell out their (mechanical or electrical) project goals (function, performance, quantity, etc.) and project constraints (quality, cost, and time limits). The need for such a design brief is repeated verbatim in every PLTW “Principles of Engineering” lesson starting with 1.4 (see the PLTW 2010 course outline).

In software engineering, projects are programs and program plans are formally called “specifications.” Influential computer engineer Leslie Lamport recently published a revealing, thoughtful summary of his views on the character and importance of such program plans (Lamport, 2015).

The Code Specification Model

Lamport is well aware of the parallels between technical writing and computer programming. Both impose a heavy cognitive load and are error-prone–“nature’s way of letting you know how sloppy your thinking is” (p. 38). A really useful code specification (like a text plan) manages this load because it “describe[s] everything one needs to know to use the code” (p. 39) before the code is written.

And such planning yields very strategic benefits: “to write a good program, we need to think above the code level” (p. 38)– that is, above the mechanical details of the programming language (here Lamport applies the coding/design distinction explained above).

Good technical writers need to do just the same– “think above the sentence level.” Of course code must have correct syntax just as a lab report or science article must have correct grammar. But one’s plan (specification) guides one “higher,” to also address:

  1. The goal of the text (share observations? defend a claim? promote safety?),
  2. The needs of the reader(s) (for reliable instructions? a big-picture project overview? a revealing comparison with something else?), and
  3. The relative importance of content details (crucial forunderstanding or just nice examples?).

Plan-Based Review

Lamport also realizes the important parallel between debugging a (draft) code and reviewing a (draft) text. Testing a draft program (debugging) reveals coding errors but “it is not a good way to find design errors or errors in the algorithm implemented” (p. 40, col. 2). Likewise, reviewing a draft text (perhaps with an editing tool like Microsoft Word but) without a plan only reveals sentence-level linguistic flaws. Plan-based review reveals text-design flaws too:

  1. Are the requirements (e.g., for a useful abstract) met, or are they too ill-defined to be met until focused?
  2. Could a reader really understand and use this text for its intended purpose?
  3. Have ambiguities been found and clarified?
  4. Is the text needlessly complex or long? Could a more simple or more concise alternative work just as well?

At the end of his defense of bothering to specify before you code (and hence bothering to plan before you write), Lamport again offers advice from science/engineering practice that applies to both activities:

Thinking does not guarantee that you will not make mistakes. But not thinking guarantees that you will (Lamport, p. 41).

Audience Awareness for (Young) Students

Always Writing for Someone

One of the keys to effective nonfiction writing is understanding just who in the real world one is writing for–audience awareness. So cultivating such audience awareness in your classroom gives your students an invaluable asset.

Even mundane school writing assignments have some “anticipated audience: a teacher, peers, parents, or the community. I have noticed[, however] that many students do not internalize this concept” (Paula Bourque, Close Writing, p. 18). Beyond school, audience is crucial: notes for oneself as an audience, for instance, or public-health messages for a broad audience of nonmedical nonprofessionals. But Bourque embraces the audience-awareness challenge even for students below grade 6. Her recent book shows how she prompts students to review their drafts from each of two perspectives by showing them a pair of posters (Bourque, p. 20).

Me Versus You

One Bourque poster (“Read for Me”) lists questions that students should ask about their success in carrying out their own (content) intentions as authors:

  1. What was I really trying to say?
  2. Do my ideas flow and connect well?
  3. Could I say something better (different word choice)?

The second poster (“Read for You”) introduces students to audience awareness by listing questions that they should ask about meeting the needs of their readers, not just themselves:

  1. Have I provided enough (relevant) detail?
  2. Are there places where you might get confused?
  3. What else do you need to know (specifics, examples)?
  4. Have I made the text easy to read (punctuation, lists, etc.)?

The Text-engineering Model

Bourque (p. 19) motivates her two-poster technique by appealing to a rather arcane literary distinction mentioned by Louise Rosenblatt in a 1988 technical report: authorial stances. The first “authorial stance” is as the writer producing the text (the default “read for me” viewpoint of many students). The second “authorial stance” is the new one for students, as the reader trying to understand the words of someone else in the draft (“read for you,” the audience perspective).

Fortunately, we have already seen a less abstract, more in-the-world way to frame the need for audience awareness: engineering design. Every designed artifact (a bridge, cell phone, or computer program) has users (= audience) and those users have needs that impose constraints on the design (total weight, hand size, speed of doing a sort, etc.) Good engineers assume from the start that early embodiments of their design are prototypes that they will change iteratively to better and better meet the needs of their artifact’s users. Student writers who come to see their readers as users of their nonfiction text are developing audience awareness in the same way. The “read for you” list (above) is just a way of helping them tune their prototype words to better meet the needs of those users.

Meeting Audience/User Needs

Another benefit of approaching audience awareness in terms of engineering design is that revision then becomes a natural part of the whole drafting process. During their first draft, nonfiction writers are naturally focused on getting the words on paper (or screen) to match the ideas in their head, a task especially absorbing for young students (Bourque, p. 163). Later, through repeated revision cycles, students can shift focus to their other big engineering responsibility, getting the words on paper (or screen) to match the interests, vocabulary, and likely applications important to their readers (who will “use” the text to carry out their own tasks).

Whole scaffolding schemes have been devised to promote audience-oriented text changes during later, after-the-draft revisions. The FIX approach of Sherman and De La Paz (Sherman, 2015), for example, uses red, yellow, and green prompt cards to help young or learning-disabled students separately, sequentially pay attention first to needed text elements (the steps in instructions, for example), then later to extra reader-support features (units, transitions, filling gaps, adding comparisons, etc.), then finally to tuning their prototype text so that it doesn’t just change but improves.

Clearly, the specific moves best to use to promote audience awareness depend heavily on the chronological age and the cognitive maturity of your student writers. But the text-as-prototype engineering insight benefits everyone (more below).

How Engineering Helps Students Revise Text

Revision Is Vital

Revising nonfiction draft text is often hard for the writer but usually vital for the reader (the “user”). On the one hand, empirical studies of students revising text that they have drafted show how cognitively demanding it is to balance

  1. their intended content (their goals),
  2. the needs of their audience,
  3. the words that they have actually generated so far, and
  4. the alternative (sets of) possible words they could use instead.

On the other hand, empirical studies that compare the usability of unrevised text (such as technical descriptions of parts, or instructions for procedures) with alternatives based on user testing reveal that “experts [= writers] are unlikely to predict more than half of the problems that readers will experience” during actual use (Schriver, p. 455). So effective text revision is an authentic communication need, not just an academic exercise.

Engineering Design Includes Prototype Revision

Fortunately for student writers, “exploring, communicating, and documenting design ideas” are key features of K-12 engineering, for example, included in the “Introduction to Engineering Design” unit of Project Lead The Way. Influential software designer Frederick Brooks, Jr., spells out the connection in two of his books:

(1) Text, like software, grows better through “incremental development” that always begins with a first draft, a prototype:

The purpose of the prototype is to make real the conceptual structure specified [= the writer’s plan for what to say], so that the client [= reader] can test it for consistency and usability. [The Mythical Man Month, p. 200]

(2) But while the first draft is a crucial step toward success, it is only the beginning of an iterative improvement process:

[This prototype] reflects only the design decisions made in the process of preparing the conceptual model [= what the writer wanted to say], and not decisions driven by implementation concerns [= how the text meets or fails reader needs when they try to use it; The Mythical Man Month, p. 270].

(3) Finally, text revision, like all rapid prototyping, often (re)shapes the writer’s plan as well as the output so far:

…in the human design of artifacts [including words], the very process of designing causes changes in the mental ideal that the design approaches. Progressive truthfulness radically helps. [Design of Design, p. 205]

Progressive Truthfulness Helps

So as text engineers, how can student writers best implement Brooks’s “progressive truthfulness” approach to revising their own prototypes?

First, they should heed Karen Shriver’s advice to begin with “macro-scale” (design) changes to their draft that will focus its assertions and sharpen its meaning. “Micro-scale” (coding) changes (e.g., to spelling and grammar) that largely leave text meaning unchanged can follow on later revision passes after the (re)design decisions are in place. (Weak writers often mistakenly reverse this order of revising.) No need to tune the syntax of a sentence that one is going to delete or replace anyway in favor of another whose meaning better responds to writer goals or reader needs.

Second, student revisers can take advantage of the scaffolds and checklists discussed in the section above on “Audience Awareness”. Paula Bourque’s suggestion (p. 168) to tape a strip of paper (cut lengthwise) along the edge of a page full of words can instantly create physical space for saving the new version of a crowded draft.

Third, students can embrace Brooks’s optimize-your-prototype vision (nicely diagrammed at NASA’s “Engineering in the classroom” site) to look for these usability improvements:

  1. missing steps and faulty start/end points for processes?
  2. comparisons that clarify content and enable its use?
  3. too many (irrelevant) details, or not enough relevant ones, for adequate understanding or execution?

This way of looking at text revision and audience analysis connects both to the adventures in engineering design that more and more K-12 students are already enjoying.

References Cited

Bourque, Paula. (2016).
Close Writing. Portland, ME: Stenhouse Publishers.
Brooks, Frederick, Jr. (1995).
The Mythical Man Month. Upper Saddle River, NJ: Addison Wesley.
Brooks, Frederick, Jr. (2010).
The Design of Design. Upper Saddle River, NJ: Addison Wesley.
Lamport, Leslie. (2015).
“Viewpoint: who builds a house without drawing blueprints?” Communications of the Association for Computing Machinery, April 2015, 68(4) 38-41 DOI: 10.1145/273634.
National Aeronautics and Space Administration. (2016).
“Engineering in the classroom,” website: http://www.jpl.nasa.gov/edu/teach/resources/engineering-in-the-classroom.php#ms
Rosenblatt, Louise. (1988).
Writing and Reading: The Transactional Theory. New York, NY: New York University, Center for the Study of Reading. Reissued by the National Writing Project as Technical Report 13.
Schriver, Karen. (1997).
Dynamics in Document Design. NY: John Wiley.
Sherman, Cindy K. and De La Paz, Susan. (2015).
“FIX: a strategic approach to writing and revision for students with learning disabilities,” Teaching Exceptional Children, November 2015, 48(2), 93-101.
Spraul, V. Anton. (2012).
Think Like a Programmer. San Francisco: No Starch Press.

Helping Students Take Better Notes

Helping Students Take Better Notes

T. R. Girill
Technical Literacy Project
trgirill@acm.org

How can you apply the psychological and historical insights from our notetaking overview to build the practical skills of your science students?

Framework Aids

The basic explanatory techniques in the good-description guidelines apply to one’s own notes, just as they help improve talks and posters in science. And as with talks and posters, the specific constraints that notetaking imposes influence how to focus those techniques on the special communication demands of this task. The “Taking Notes Effectively” checklist “reveals this magic” to students by

  • exposing the common framework (left column) that general descriptive techniques and specific notetaking techniques share, and also
  • spelling out how to apply and extend these techniques (right column) to make one’s own technical notes more usable.

This checklist thus brings cognitive apprenticeship to bear on building student notetaking skills: first expose the hidden moves that “masters” routinely (but unobtrusively) use, then promote iterative practice toward mastery of those same moves by students.

Scope Management Aids

Frederic L. Holmes’s historical study of Hans Krebs’s laboratory notebooks (see “Noteworthy Content” in the overview) revealed one common weakness in the notes taken by young scientists: their scope is too narrow. This failure to thoroughly record (and thereby share) one’s own goals, plans, and struggles is so common a trait among scientists and engineers that historians of science even have a name for it: lack of interiority (Bycroft, 2010). Like so many flaws in (personal and) professional life, however, this can largely be cured with a few well-chosen techniques.

The “Taking Notes Effectively” chart therefore offers students some scaffolding to promote a more inclusive, strategic approach to notetaking. They should still not clog their notes with trivia, of course, but this chart gives them three sets of thematic cues for building more inclusive notes:

  • Under “Organization” (left column) are reminders (right column) to include (and make explicit) the relationships among their note entries (reasons, examples, etc.).
  • Under “Content” (left column) are reminders (right column) to stretch their notes to cover not just claims or data but also the goals, pitfalls, or influences that shape and explain the data (to others).
  • Under “Signals” (left column) are reminders (right column) that lists, tables, and diagrams often serve more effectively that plain text for useful capture of scientific information.

Even students who take conscientious notes (clear, organized, specific) can benefit from such scope-management aids because, as biologist Robert Barrass warns his junior colleagues, “Things which seem unimportant during an investigation may prove to be important later” (Barrass, 2002, p. 11). “Later” might mean simply for an end-of-term exam, or it might mean for subsequent lab or field research (just as in life after school).

Usability Management Aids

The Case of Darwin’s List

A document that captures a dispute between Charles Darwin and his father Robert in 1831 provides a nice history-of-science example of how the techniques listed on “Taking Notes Effectively” can improve the usability of science notes. (Your students can work the historical case sequentially themselves, as shown here, or they can use it as a model for improving their own notes.)

In August, 1831, Charles Darwin received an invitation to serve as naturalist on a round-the-world voyage by the HMS Beagle (the trip that greatly influenced his developing views on species evolution). His father argued against taking the job, however, offering many personal and professional objections, which Charles summarized in these words (see Dolgin, 2009):

Darwin's summary in paragraph

In this paragraph format the summary is not very usable, however. That is probably why Darwin himself arranged his words instead as an explicit list of objections (he numbered each one not because their order is important, the usual reason, but for convenient reference). This is a reproduction of Darwin’s own handwitten list:

Darwin's handwritten list of objections

And here is the same text reprinted for easier reading:

Darwin's list printed

 

Grouping related content items together under headings that reveal what they have in common is a different standard way to improve their usabilty:

Darwin's list grouped under headings

And a scientist can certainly combine these usability techniques to amplify the benefits of each alone:

Darwin's list using combined usability techniques


So this case illustrates how deploying in one’s science notes the same good-description techniques familiar from other contexts can improve the ease with which their author as well as others can use those notes to achieve practical ends. For Darwin, itemizing his father’s objections enabled his uncle (Joshiah Wedgwood) to draft a specific rebuttal for each point in turn. When presented with these point-by-point replies, Robert Darwin relented and allowed Charles to take the voyage that revolutionized biology.

The Dual-Column Case

The previous examples involve techniques for note improvement that also apply to other technical texts. But special usability scaffolds also exist that are seldom appropriate elsewhere yet often boost the effectiveness of technical notes.

The most influential of these note-specific improvement techniques is the use of a two-column format: one’s primary notes go into a (relatively wide) right-hand column and diverse commentary goes into a (relatively narrow) left-hand column on every notebook page. Swarthmore’s Colin Purrington explains why splitting each note page vertically improves the usability of notes: “Keeping a notebook gives you a forum to talk to yourself, to ask questions” (Purrington, 2009). Using two columns gives you a place to carry on that conversation, namely, in the left-hand column of every page.

This two-column scaffold has been much publicized by Cornell University, and many people call this approach “Cornell notes.” I suspected that this technique predated Cornell’s influence, however, since attorneys and college debaters everywhere often use a similar dual-column note format to capture in parallel what their opponents are claiming and how they plan to counter each claim.

Actually, the history of science reveals that the usability benefits of two-column notes were recognized 500 years ago. In his journals and notebooks, Leonardo da Vinci, writing around 1500, used two columns to align his diagrams with his explanatory text, as this sample shows:

page from da Vinci journal

The arrangement seems a little strange because da Vinci used mirror writing to disguise his text, so the left (secondary) and right (primary) columns appear reversed. Here is the same page flipped over, to reveal his strikingly modern notes-with-commentary format:

da Vinci's journal page flipped

For the science classroom, several variations on this dual-column scaffolding are available to prompt student self-comment.

  • The Basic Template.Blank templates on to which students can take their own “Cornell notes” can be freely downloaded from the Internet.
  • The Cued Template.
    More elaborate versions that add brief cues (section labels, suggested content, short-cut tips) can help younger or less mature students remember how to take advantage of the dual-column note format. 
  • The Customized Template.
    Robert Barrass (p. 11) encourages science students to design (and then reuse) their own customized two-column note template whenever they need special support for recurring data tables or annotated diagrams. Here is one simple example:
    Customized template from Robert BarassThe (linked) HTML file for this case lets your students easily edit this framework to suit their specific note-taking needs.

Together, these three alternatives make using dual-column notes a straightforward opportunity for differentiated learning.

Revising Notes

Using any two-column note template implies, even encourages, “improving” one’s original notes (by adding comments and other usability aids) after capturing a first version. Likewise, ethnographic studies of working biologists have revealed that some take notes in two stages (quick but crude, then redrafted more carefully into formal notebooks). Of course, such editing can change the evidence value of notes in patent or priority disputes. For students struggling to create merely adequate lab or lecture notes in class, however, such legal concerns may never arise and improved usability for themselves may be everyone’s primary goal.

References

Barrass, Robert. (2002).
Scientists Must Write, 2nd edition. London and New York: Routledge.
Bycroft, Michael. (2010).
Adventures in romantic science. History of Science Newsletter, January, 39(1), 20. Online at http://www.hssonline.org/publications/Newsletter2010/January adventures-romantic-science.html
Dolgin, Elie. (2009).
Darwin vs. his dad, circa 1831. The Scientist. 23(2), 72. Online at http://www.the-scientist.com/article/print/55374