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.