|
–Geoff-Hart.com:–Editing, Writing, and Translation —Home —Services —Books —Articles —Resources —Fiction —Contact me —Français |
You are here: Resources --> 2001 --> Shakespearean
technical writing
Vous êtes ici : Ressources --> 2001 --> Shakespearean
technical writing
By Geoff Hart
Previously published, in different form, as: Hart, G.J. 2001. Shakespearean technical writing. Intercom March:22–24.
The notion that people don’t read manuals the way they read books pops up periodically on techwr–l (an Internet discussion group for technical writers). The reasoning goes like this: manuals exist to solve problems, not for reading pleasure.
The usual corollary to this observation? That technical writing is not literature, and thus doesn’t borrow from the vast repertoire of tricks that literary writers use. One correspondent went so far as to state that unlike Shakespeare, we don’t use metaphor, foreshadowing, rhyme and meter, alliteration, and “fortuitous circumstance” to create meaning. Few technical communicators would disagree; in fact, the assertion that we don’t write literature has become something of an article of faith for our profession.
Not being one to accept a prevailing dogma at face value, I’d venture to disagree. Despite an occasionally highly inventive fictional component (software documentation and the reality it purports to describe are often in clear conflict), our manuals will never make the New York Times bestseller list. But that's not because the techniques Shakespeare used lack merit in technical writing; rather, it's because we (myself included) fall too easily into familiar patterns and forget to apply those techniques, suitably adapted to a different medium and purpose. Interestingly enough, each of the aforementioned literary techniques has a parallel in technical writing that is probably either underused or used unconsciously and thus ineffectively.
Metaphors (and their cousins, the similes) use the reader’s familiarity with one concept as a means of helping the reader understand a different but conceptually similar concept. Demonstrating the similarities between the two concepts improves comprehension because the reader has already done the work required to understand one concept, and doesn’t have to repeat that work to understand the new concept.
Technical communicators frequently use metaphors to make unfamiliar concepts resemble something familiar. The trashcan icon on the Macintosh desktop and its cousin the Windows recycle bin are two familiar examples. Both conceptually resemble the trashcans found in every office: they hold discarded documents until we either retrieve or dispose of them. The power of such metaphors lies in their ability to make abstract, unfamiliar, potentially intimidating concepts (management of the small magnetized areas on a hard disk) appear concrete, familiar, and less intimidating. In so doing, metaphors ease our readers past the barriers imposed by their discomfort with new concepts and thereby help them learn to use a product.
The problem with metaphors is twofold: writers sometimes take them further than the metaphors merit (thereby misleading users), or they create mixed metaphors that prevent users from correctly understanding how something works. Apple’s original trashcan icon exemplifies the first problem, since the operating system deleted the trashcan’s contents when you shut down the computer. Although that made perfect sense in a business environment, where cleaning staff collect the trash every night, many home users expected the trash to remain full until they “took out the garbage” themselves. This misunderstanding led to frequent enough loss of files that Apple eventually fixed the problem in later editions of the Macintosh operating system (an approach later adopted by Windows).
Similarly, the Windows metaphor of a Start menu from which users could start up any program made perfect sense for starting programs but broke down when more than just programs got added to the menu; the most glaring problem is that many new users simply can’t understand why they must open a start menu to stop their computers.
In literature, foreshadowing is the art of dropping hints of what is to come, whether a description of the snow mass poised atop an alp and waiting to bury a small Swiss town in an avalanche, or the storm clouds that build as a metaphorical storm approaches in the protagonist’s life. In technical writing, we borrow from the jargon of “metadiscourse” and call foreshadowing "using advance organizers" (clues that let readers build a framework by preparing them for whatever new material they’ll encounter), or we invoke “schemata” (which provide or refer to mental models of a process or a concept).
Any time we provide context that helps readers to understand subsequent material, we're using foreshadowing to get them ready to absorb a new concept. Foreshadowing also functions at more subtle levels, such as when we use however to warn readers that they’re about to encounter an exception or drawback, or thus to indicate that an argument has reached its end and that the next words will summarize what we’ve said in the form of a conclusion. Those who adopt the doctrine of minimalism without fully understanding it often make the mistake of considering such forms of foreshadowing to be superfluous. They aren’t always.
The trick in producing usable documentation lies in understanding just how much foreshadowing readers need before they can proceed. You must understand your audience well enough to know what knowledge they bring to the learning process before you can make this decision. On the one hand, providing context that they already possess wastes space and conceals important new information within redundant older information. On the other, failing to provide this context for those who lack it forces them to construct their own context; if they succeed, they’ve wasted time you could have saved them by providing the context, and if they fail, you’ve probably failed to communicate.
Before mass production of books, paper was sufficiently rare and expensive that people had to rely on their memories to preserve information; in fact, some Greeks of Homer’s time had good enough memories that they could memorize all or most of long epic poems such as The Iliad. Unfortunately, this talent has grown somewhat rare; most of us moderns have trouble remembering a new friend’s phone number or the password to our computer network. To help their contemporaries remember such long works, ancient authors commonly reshaped sentences using rhyme and meter: by repeating patterns of syllables and using words that guided readers firmly toward the words that followed, the author emphasized the structure, helped speakers recall what words would follow, and thereby facilitated memorization.
Rhyme can be such a powerful cue to what comes next that it has created a standing joke about pop music: any line in a song that ends with the word change will be followed inevitably by a line that ends in rearrange (the only Word in the English language that rhymes with change). Similarly, meter defines the number of syllables that can fit at a given position in a line and thus limits the list of words that might conceivably be found at each position; as a result, memorizers need only consider words with the correct number of syllables. Now that we can record poems and literature so easily in print or electronic form, we’ve eliminated the need to memorize literature, and this may be one reason why rhyme and meter have fallen out of fashion in several modern styles of poetry. But for things that we don’t commonly encounter on paper, such as the lyrics of pop songs, rhyme and meter remain important in making the words memorable.
A software manual written like poetry, rhymed or otherwise, would certainly have some merit; for example, I’d savor the irony of a future manual for Microsoft Office written to imitate Percy Bysshe Shelley’s poem Ozymandias. But since few people other than technical writers read manuals for pleasure, a manual imitating Ozymandias would represent a too-literal application of rhyme and meter. For technical writers, the obvious counterpart to rhyme and meter would be stylistic rules that lead to more consistent or simpler sentence structures by keeping together dependent parts of speech (such as verbs and adverbs), streamlining sentences to avoid excessive clauses, using words that not only say the right thing but also "taste" right (i.e., that follow the prevailing usage patterns), following a consistent structure (e.g., ensuring that each entry in a reference manual contains the same classes of information), and so on. Combined with the correct use of foreshadowing to prepare readers for words and meanings to come, such rhythmic writing can be a powerful tool for making documentation more comprehensible.
The problem with using rhyme and meter or their technical writing equivalents arises when the device attracts enough attention to itself to draw the reader’s attention away from the material. Form and function are equally important in some types of communication, but in technical communication, form should never detract from the function: clear communication.
Alliteration creates a pattern of repeated initial sounds (e.g., theoretically throttled thespians) that takes advantage of the human mind's remarkable ability to detect patterns. In this example, repetition of the first letter or syllable creates a pattern that reinforces the impression that the individual words function together as a single unit.
The most obvious way to use this technique in technical writing would be to create bulleted or numbered lists; the bullets and numbers form the repeated element that catches the eye and identifies the list items as belonging together. Other examples might include repeating a chapter title as a running head on each page, or using consistent designations such as “Figure” and “Table” to identify all figures and tables as being part of the same class.
[A look back from 2005: There are also many metadiscourse techniques that benefit from alliteration. Consider, for example, repetition of a prefix of some sort to reinforce parallelism, to make the relationship of the words clearer, and to illustrate the technique in the sentence you're currently reading.—GH]
The problem with alliteration (as with rhyme and meter) arises when it draws so much attention to the technique that it draws attention away from the content. I’ve seen authors fall into this trap in technical reports by using long lists where carefully constructed, logically linked paragraphs of body text would work better, or where (in shorter bulleted or numbered lists) the first several words after each bullet or number are identical. I’ve also seen endless hyphenation at the right margin of fully justified text create a “picket fence” of hyphens that draws the eye just like any other form of ornamental border. The solutions were (respectively) reassessing the information to permit a rewrite as linked paragraphs, placing the repeated words in the sentence that introduced the list so they did not have to be repeated in each bullet, and limiting the software to a maximum of three consecutive hyphens at the ends of lines.
In drama, “fortuitous circumstance” involves lucky coincidences and the classical deus ex machina solution that arrives at just the right time to save the protagonist.
Though this literary device might seem entirely out of place in technical writing, a closer examination reveals that we probably rely on fortuitous circumstance more than any other technique and more than skilled literary writers would ever consider doing. After all, what else would you call context-sensitive help and what’s this? pop-ups and tooltips? One might even make a case that the minimalist philosophy of “just in time” information is an example of fortuitous circumstance.
The beauty of this technique is that it saves our heroic users by providing what they need when they need it; the problem, of course, is that it’s necessary at all. The holy grail of user interface design lies in creating an interface so obvious and so usable that context-sensitive help becomes unnecessary. Although it’s not realistic to expect that we’ll achieve such interfaces anytime soon, it’s certainly realistic to hope that by working with programmers, we’ll be able to minimize the amount of deus ex machina required—or at least put the deus back in the machine, where it belongs, more often.
It’s clear that even with the best intentions and our utmost efforts to write well, we’re unlikely to find our reference manuals being studied in literature classes—let alone being performed on stage. But this doesn't mean we can't use the same techniques the great writers used; after all, the underlying principles of human comprehension are identical, whatever the medium. It’s just the manner in which those principles are applied that changes. What other literary techniques might we be neglecting?
©2004–2024 Geoffrey Hart. All rights reserved.