Technical Writing Explained

T. R. Girill
trgirill@acm.org
Technical Literacy Project
September, 2008

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 and exercises 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 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

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 703-page Technical Communication (8th edition, 2007)). 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. Passages 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. The audience problems that such text must address include:

(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 American Society for Information Science and Technology (ASIST, 2008) 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 engineering practices for the "design of communication" (SIGDOC, 2008). 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:

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. Sommerset Maughm 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). They draw on insights and studies in

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. (2008).
American Society for Information Science and Technology website. http://www.asis.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. (2007).
Technical Communication 8th 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).
Abstracts: problems classified from the user perspective. Journal of Information Science. 31(8), 515-526.
Schriver, Karen. (1997).
Dynamics in Document Design. New York: John Wiley.
SIGDOC. (2008).
Special Interest Group on Design of Communication, Association for Computing Machinery website. http://www.sigdoc.org
Tuchman, Barbara. (1981).
Practicing History. New York: Ballantine Books.