Technical Writing Explained

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

Handbook Table of Contents

Goal: Supporting Writing’s Place in Science

In 1978, field biologist Robert Barrass, prompted by repeated requests from his science colleagues and friends for help with their professional writing, collected his advice into a guide called Scientists Must Write. That little book never went out of print. When Barrass updated it in 2002, he added this explanation to his preface:

Writing is part of science, but many scientists receive no formal training in the art of writing. There is a certain irony in this: we teach scientists and engineers to use instruments and techniques many of which they will never use in their working lives, and yet do not teach the one thing they must do every day–as students, and in any career based on their studies….This book, by a scientist…is about all the ways in which writing is important to students and working scientists and engineers in helping them to observe, to remember, to organize, to plan, to think and to communicate (Barrass, 2002, p. xv).

The professional development material that you are now reading complements Barrass’s efforts. Its goal is to help high-school teachers integrate some authentic yet age-appropriate, classroom-tested, skill-building writing activities into science classes. The approach explained here has proven itself with underperforming as well as AP students, in urban as well as suburban California high schools since 1999. The strategies and cases shared in this handbook have been iteratively refined during an ongoing “technical literacy” project jointly sponsored by the East Bay chapter of the Society for Technical Communication (STC) and the Computation Directorate of Lawrence Livermore National Laboratory (LLNL). In 2005 this project received an international Pacesetter Award from STC for “delivering excellent education about our craft to high school students.” In 2007 it earned an STC Distinguished Service Award, reserved for only the most outstanding 1% of society-sponsored community outreach activities.

Motivation: Why Science Teachers Should Bother

The Next Generation Science Standards organize science into eight “practices” or intellectually framed but socially embedded activities. While five practices are investigational (e.g., analyze data), three overtly focus on science/engineering communication: develop explanations, argue from evidence, and share information. These last three practices amplify any scientist’s or engineer’s success with the first five, which makes them highly relevant to the science (not just to the ELA) classroom. This section unpacks that relevance.

The purpose of this introductory section is to give you, as a teacher, a good mental model of technical writing’s place in the universe of text. This is a topic seldom discussed in high school. Yet, as Barrass suggests, every science student can benefit from becoming aware of, then hopefully mastering, basic technical writing techniques, whether that student’s future lies in research or practice, in the academy or industry. With technology diffusing so thoroughly through ordinary life, even fulfilling daily citizenship and parenthood duties now demands some technical writing and reading skills. The model presented here is simple yet revealing. You can use it to

  • guide your own lesson planning and classroom practice, and
  • frame or clarify specific exercises for students too.

This is not intended as a crash course in how to become a professional technical writer. Plenty of large and detailed textbooks already address that different need (for example, see Mike Markel’s well-regarded 700-page Technical Communication (10th edition, 2012)). Rather, this section offers a conceptual map for science teachers to organize the design issues that face every drafter of technical text and the skills and techniques known to deal with those issues.

Sharing this information with students (especially during their high-school years) is not a responsibility that one can safely leave to others. Official and unofficial educational standards require it, as the standards section reveals. Beyond that narrow formal responsibility, however, lies a broader need for sound “technical literacy” among all young people.

Mathematics teacher Michael C. Burke nicely summarized this need on behalf of the Carnegie Foundation for the Advancement of Teaching when he said:

What we think is intertwined with how we think….I would propose that we begin by redesigning our freshman and sophomore writing programs in order to place a significant emphasis on working with quantitative data, and on the visual representation of that data. We write, after all, to figure out what we think. And we ask our students to write so that they will learn how to think. (Burke, 2007, p. 2)

Even more striking is how Burke elaborated this proposal in a next paragraph deleted, perhaps over concern about backlash from the language arts community, when his article was reprinted in AFT On Campus (Burke, 2008):

I can imagine that many who oversee our writing programs would not be eager to implement such a program. After all, it is perhaps asking them to teach our students to think in ways that they themselves do not think….It is well past time for those of us with a quantitative cast of mind to become involved in a serious way with the writing programs on campus. For the majority of our students, this is where the action is, and accordingly, this should be one of the places where we concentrate our efforts.

Further evidence of this link between effective technical writing and thoughtful science appeared in a recent critical review of student papers submitted to the annual American Society of Human Genetics essay contest (Mills Shaw, 2008). The contest judges, in a March 2008 public report, complained that “another significant observation we made after reviewing 2446 [high-school science] student essays is that students need to be instructed in writing with precision….it is clear that students are not being taught to write using technical language and appear to approach their scientific writing in the same [casual] way they might as an essay for an English…assignment” (p. 1166). Improving writing performance pays a direct benefit for the science classroom too: “precise language usage appears even more important in scientific fields because it is not merely a vehicle for communicating understanding, but itself actively facilitates learning and comprehension” (p. 1167).

Comparative Overview: The Universe of Text

Perhaps the best way to explain technical writing from a teaching perspective is to contrast it with what it is not. Invoking such “contrast classes” is a proven strategy for introducing any new concept (“perceiving the distinctions between one group and another may be an essential part of perceiving the characteristics of each group” (Fleming and Levie, 1978, p. 67)). Completing the process calls also for some choice examples of different kinds of writing, since learning a concept often requires both positive examples and “close-in” nonexamples of the concept’s defining criteria (e.g., Foshay, Silber, and Stelnicki, 2003, p. 85).

The Quadrants

The universe of written material can be revealingly divided into quadrants based on (1) each text’s own structure and on (2) its (intended) relation to the world (Girill, 2004). The latter distinction (fiction or nonfiction) is widely known, while the former (narrative or nonnarrative) is often noticed only by professional communicators or text linguists:

Fiction Nonfiction
Narrative
Nonnarrative

Fiction is by design imaginary or made up (although it often includes a mix of real people, places, things, or events for flavor). Nonfiction is intended to be factual, to represent only the world, perhaps incompletely but exclusively. The fiction/nonfiction distinction should certainly be familiar to high-school students; I am always dismayed when some confess that it is news to them.

The narrative/nonnarrative distinction, however, is one that all students have seen in practice but few know by name. To narrate is to tell as a story, the default way that most humans structure text (e.g., see Grundlach in Nystrand, 1982, or Ch. 10 in Flower, 1981). Narrative prose is organized as a series of events. If no other “natural” series is available, the story teller can always use the sequence in which events became known to them, that is, they can recount their biography of personal discovery. A key feature of all narrative text is the progressive disclosure of story elements: things are never revealed all at once, but rather through a (perhaps carefully planned or managed) sequence. Progressive disclosure builds suspense (crucial to mysteries but present in all narratives), one practical side effect of which is prolonging reader interest.

Nonnarrative text, although common in modern life as we shall see shortly, is something that most people must consciously learn to construct. Explanations here are explicit and key details are overt. Important information is not held back or deferred to prolong interest, because most readers of nonnarrarive prose already have a strong external motivation to read the text (usually, as noted below, to answer a pressing question). Nonnarrarive text structure is usually hierarchical or clustered by topic (e.g., Girill, 1985), seldom just a chronological series, and linguistic signals within the text usually make that structure obvious for the reader (no mysteries here). Also, nonnarrative texts often use visual features (e.g., headings) to highlight key claims and text chunks for easier reading and retrieval. Such features are very rare, perhaps even counterproductive, in typical narratives.

Narrative Fiction

Narrative fiction is the quadrant (upper left) or subset of the text universe with which high school students are most familiar because they meet its members so often in English class: novels and short stories. Here students confront implicitly structured and progressively disclosed stories, sometimes hundreds of pages long. The writers of such narrative fiction usually have creative self-expression as their primary goal (to write a more clever story than its countless but similar predecessors). Character development, dialog, and point of view are thus major challenges for writers of fiction. Maintaining reader interest to the end, often with intricate literary (but not visual) devices, is a vital secondary goal (for writers who want to keep their publishers happy). Readers will not find bulleted lists, subsection headings, or explanatory tables in the chapters of a typical novel. And the audience for narrative fiction usually must be recruited, perhaps with advertising or author appearances, from a somewhat indifferent public.

Nonnarrative Fiction

Not all fictional works are narratives. While epic poems were once common, most modern poetry is not story oriented in either content or structure. Likewise, much drama that students encounter in English class today (such as the plays of George Bernard Shaw) focuses on dialog, character interaction, or even the author’s political positions. Printed (not spoken) works in the lower left quadrant, unlike most in the upper left, often do employ elaborate genre-specific visual cues (indenting for poetry, script layout and scene labeling for plays). Once again, the audience for nonnarrative fiction is usually hard-earned poetry lovers or theater fans in a crowded market. And the dominant goal is, once again, creative personal expression.

Narrative Nonfiction

The texts in the upper right quadrant, as nonfiction, bring us closer to the material that students see in science classes. Familiar (to students) nonfiction works organized narratively include biography, history, and much news. Most biography, for example, reveals the story of some real person’s life. ‘History’ contains the string ‘story’ for a reason: talented historians are not only experts at archival research and interpretation, but also at constructing thoughtful narratives about past events and people. “No one could possibly persuade me,” declared nonacademic historian Barbara Tuchman, for instance, “that telling a story is not the most desirable thing a writer can do” (Tuchman, 1981, p. 49). Even news items are usually called “stories” because they report current happenings in a special, cyclical, progressive-disclosure pattern that professional journalists study to master.

The goal of most narrative nonfiction, unlike fiction, is to reveal or explain world events, current or past. Hence the audience expects and the writers strive to provide lucid, coherent, useful exposition. This is a rather different set of reader demands and writer skills than most fiction involves. The relation of this text to its “market” is different too: readers want to have their information needs (not just their desire for entertainment or surrogate experience) met here, and they judge the success or failure of texts in this quadrant accordingly.

Nonnarrative Nonfiction

In contrast to the other three quadrants surveyed above, the texts in this one (lower right) arise from what is generally called “technical writing.” They deal with the real world (nonfiction) by structuring their topic treatment other than as a story (nonnarrative). All are loosely either instructions (for performing some task) or descriptions (of some thing or process). Barrass gives a one-page itemized list of many specific examples from this quadrant familiar to working scientists (Barrass, 2002, p. 17, where he includes user manuals for equipment or software, laboratory notes or reports, and scientific articles). So now the chart with cases added looks like this:

Fiction Nonfiction
Narrative
  • Novels
  • Short stories
  • Biography
  • History
  • News
Nonnarrative
  • Drama (some)
  • Poetry (some)
Technical writing

  • Instructions
  • Descriptions

The texts in the lower right quadrant differ from most of the others on the chart because of their especially compelling or practical role for their audience. People eagerly read (usually consult passages from, not peruse from start to finish) technical instructions and descriptions because the readers have problems for which they seek solutions in the text. Nonnarrative nonfiction is almost always problem-solving prose, and those who write it well design it accordingly, working as “text engineers.” The audience problems that such text must address include:

  • External problems (outside the text):
    • How to make, use, install, or repair something
      (for example, how to replace a bathtub or extract DNA from human cheek cells).
    • How to understand the features or role of something
      (for example, how do fluorescent lights work and can the mercury inside them be eliminated).
  • Internal problems (within the text itself):
    • How to easily find answers in the text.
    • How to comprehend the answer passages once found.
    • How to detect relevant information chunks amid irrelevant background.

(These internal problems receive a longer treatment in the section on text usability.)

Discovering how to prepare text that adequately solves such communication problems calls for a challenging empirical research program. And this challenge cuts across scientific disciplines. For example, one special interest group of the Association for Information Science and Technology (ASIST, 2016) concentrates just on information “needs, seeking, and use” by those who read technical text. Another special interest group of the Association for Computing Machinery focuses on good text-engineering practices for the “design of communication” (SIGDOC, 2016). And since science is international, linguists and sociologists also worry about how to achieve technical text adequacy across languages and cultures (e.g., Montesi and Urdiciain, 2005). The results of this research affect everything from the content of scientific journal articles to the arrangement of data on food-can labels.

Educational Relevance

Technical writing thus has three important, educationally
relevant properties:

  • Authenticity.
    Some writing coaches suggest science fiction stories as a creative way to promote interest in science class (Cody, 2008). Writing fiction (even science fiction) is chiefly a school skill, however, not preparation for life. Most would-be novelists never get published. Writing effective nonfiction (instructions and descriptions), on the other hand, contributes to success in virtually all technical jobs across the knowledge spectrum from basic technician (Papantoniou, 2016) to medical practitioner, researcher, or engineer. Away from school, most students will find that technical writing even helps them succeed as parents or citizens, not just as employees.
  • Efficiency.
    Because of its differences in features and role from texts in the other three quadrants above, technical writing often reveals to students a concept vital to efficient learning about anything: cognitive load. Most teachers but few students recognize cognitive load as the mental processing demanded by each new task that a learner confronts (Forshay, 2003, p. 218, for example). The more that students learn about managing cognitive load as they practice good text-design techniques (to minimize it), the better they become at managing their own learning activities. This is the metacognitive fringe benefit hinted at by the genetics essay-contest judges quoted earlier.
  • Learnability.
    In a recent short survey article (Mendoza-Denton, 2008), UC Berkeley psychologist Rudolfo Mendoza-Denton summarized several studies that showed how pronouncements about student technical-skill malleability are actually self-fulfilling. For example, middle school students told (by researcher Lisa Blackwell) that with active practice “you can grow your intelligence” subsequently did perform better using math skills than a control group told that their intelligence was fixed. This is just the problem facing high-school students with writing anxiety or a poor track record on past nonfiction writing assignments. Many believe that their writing success is fixed and that they are doomed to failure. Actually, effective technical writing is largely a matter of learned and learnable techniques. The guidelines (checklists) and student activities linked from other sections of this handbook externalize those techniques. Merely reading them does not make one a skilled practitioner, of course. But, with teacher encouragement and an apprenticeship approach, these tools can seed confidence that skill building is possible as well as show students an iterative, scaffolded path to those better writing skills.

Significance for Teaching

How could you help the students in your classes become better at such technical writing, at crafting more adequate nonnarrative nonfiction text not just for school assignments but for life after school as well? Successful British novelist W. Somerset Maugham once reputedly remarked that “there are three rules for writing a great novel; unfortunately, nobody knows what they are.”

As the analysis above suggests, however, we are not in that spot regarding technical writing. How to perform well here is an empirical question on which much interdisciplinary research has been done since the late 1970s with largely convergent results. The “rules” for creating successful technical text are fairly well understood (one good recent survey is Schriver, 1997; see also Markel, 2012). They draw on insights and studies in

  • rhetoric–the traditional analysis of arguments,
  • engineering–treating text, like other artifacts, as an object for careful, informed, iterative design, and
  • psychology–which reveals the relevance of cognitive apprenticeship to teaching writing and mental models to learning it.

The remainder of this handbook describes a teaching path forward using this knowledge, whose practical value has been tried, refined, and demonstrated with real high-school students, often under adverse teaching conditions and for chronic underperformers, since 1999.

References

ASIST. (2016).
Association for Information Science and Technology website. http://www.asist.org
Barrass, Robert. (2002).
Scientists Must Write. London: Routledge.
Burke, Michael. (2007).
A mathematician’s proposal. Stanford, CA: Carnegie Perspectives. Available
online at http://www.carnegiefoundation.org/perspectives/sub.asp?key=245&subkey=2451
Burke, Michael. (2008).
A mathematician’s proposal [adapted]. AFT On Campus. 27(3), 14, Jan/Feb 2008.
Cody, Anthony. (2008).
Best practices. Teacher Magazine. May 7, 2008. Available online at http://www.teachermagazine.org/tm/articles/2008/05/07/32tln_cody.h19.html
Fleming, Malcolm and Levie, William. (1978).
Instructional Message Design. Englewood Cliffs, NJ: Educational Technology Publications.
Flower, Linda. (1981).
Problem-Solving Strategies for Writing. New York: Harcourt Brace Jovanovich, Ch. 10.
Foshay, Wellseley R., Silber, Kenneth H., and Stelnicki, Michael B. (2003).
Writing Training Materials That Work. San Francisco: Jossey-Bass/Pfeifer.
Girill, T. R. (2004).
Documentation as problem solving for literacy outreach programs. UCRL-CONF-205156. Society for Technical Communication 2004 Region 8 Conference, UC Davis, July 25-27, 2004. Available online at https://e-reports-ext.llnl.gov/pdf/309320.pdf
Girill, T. R. (1985).
Narration, hierarchy, and autonomy: the problem of online text structure. In C. A. Parkhurst, Ed., Proceedings of the 48th American Society for Information Science Annual Meeting, vol. 22, Las Vegas, NV: ASIS, pp. 354-357.
Grundlach, Robert. (1982).
Children as writers: the beginnings of learning to write. In Martin Nystrand, Ed., What Writers Know. New York: Academic Press, Ch. 6, pp. 129-69.
Iorio, Shawn, and Garner, R. R. (1988).
Scholastic journalism enrollment changes. Available online at http://www.eric.gov/ERICWebPortal/recordDetail?accno=ED305627
Markel, Mike. (2012).
Technical Communication 10th Edition. Boston: Bedford/St. Martins.
Mendoza-Dennton, Rudolfo. (2008).
Framed. Greater Good. 5(1), 22-24. Available online at http://greatergood.berkeley.edu/greatergood/2008summer/Mendoza-Denton651.html
Mills Shaw, Kenna R.; Van Horne, Katie; Zhang, Hubert; and Boughman, Joann. (2008).
Essay contest reveals misconceptions of high school students in genetics content. Genetics. 178 (March), 1157-1168.
Montesi, Michela, and Urdiciain, Blanca. (2005).
Papantoniou, Eleni, and Hadzilacos, Thanasis. (2016).
WEB based technical problem solving for enhancing writing skills of secondary vocational students. Education and Information Technologies.
(July). DOI: 10.10076/s10639-016-9520-y.
Schriver, Karen. (1997).
Dynamics in Document Design. New York: John Wiley.
SIGDOC. (2016).
Special Interest Group on Design of Communication, Association for Computing Machinery website. http://sigdoc.acm.org
Tuchman, Barbara. (1981).
Practicing History. New York: Ballantine Books.