By Dr. Mati Schwarcz
YEDA

A significant part of a technical writer's tasks includes rewriting or editing original material. Too often, writers, intimidated by the technical jargon and "facts" are left carefully mending grammatical elements in the text, dotting I's and crossing T's - and leaving the piece nearly as unreadable as it was when they received it. For example, consider the following piece:

"The ABC is a powerful graphics rendering system that includes both hardware and software modules. ABC devices can be chained together to greatly multiply performance. On the hardware side, the ABC is composed of a digital device containing graphics cards and associated ABC cards. The ABC cards can render graphic images in real-time."

On the purely grammatical side, this paragraph is fine. On the stylistic side, it is not particularly brilliant - but it is adequate - sentences are a modest length, sentences are cohesive in that they link from one to another - everything is in order and the paragraph makes sense. Now consider this version:

"The ABC is a powerful graphics rendering system that includes both hardware and software modules. On the hardware side, the ABC is composed of a digital device containing graphics cards and associated ABC cards that can render graphics images in real-time. The power of the ABC lies in the fact that several ABC devices can be chained together to greatly multiply performance."

Same sentences, same grammar, similar style - so why does the second version sound a lot better? What's the difference? Here we need to appeal to principles of rhetoric. The second version introduces an important rhetorical element that was missing in the first - it establishes a focal point, the system's power, and it tells why it is so powerful. This doesn't mean that the first version didn't give the same facts - but it did not explicitly make a point - it simply related facts having to do with the ABC system.

All too often, this rhetorical dimension is simply missing, and the editor, who is merely looking for adherence to grammatical rules, style, and technical accuracy, doesn't bother to try to uncover it either. So the piece is passed along, another collection of assorted facts for the reader to wade through.

Why Do Technical Communicators Need Rhetoric?
The use of rhetorical argument in technical writing may seem strange - after all, technical writing is about directly explaining and instructing - so where does rhetoric come in? To understand what rhetoric has to do with technical writing, it's important to examine the claims expressed by the innovators of modern rhetoric, such as Kenneth Burke - the claim that ALL language, to be meaningful, is inherently rhetorical. All communication makes some point, or tries to convince the audience of something. This is as true for speech as it is for writing, and it applies as much to the explanation of a software feature as it does to a love poem. The difference between experienced and inexperienced communicators simply lies in their awareness of this fact. Inexperienced communicators often do not have a clear idea of what point they are trying to make, or of what they want to show the audience - while experienced communicators know what they want to say, what they want to convince the reader of, and how to do it.

What Kind of Rhetoric Does Technical Writing Need?
The starting point for any writer, then, and this includes the technical writer, is the question "why am I writing this?", or "what is this piece meant to communicate?" Too often, technical writers content themselves with the simple answer of "This gives information about X".

On the surface of things, this seems a plausible answer - after all, technical documentation is, primarily, a medium to relay information about some product, or feature that someone else - a user, a developer, an administrator, etc. - needs to know about. But this is not really an adequate answer - if it were, we could simply supply tables or lists of clear, accurate, and detailed facts pertaining to each feature of the product being documented - this would communicate the needed information, but it would not qualify as good technical writing. Why? Because, in addition to the information itself, readers need to know the purpose and the significance of the information.

For example, consider the following piece:

"Working with X is easy.  The Edit and Format menus, which are used to edit and format text, are found at the top of the screen. Below the menu area, you will find the toolbars. Scroll bars are located on the side and bottom of the screen. Along the bottom of the screen is the status area."

This is a string of loosely held together facts, typically followed by a labeled screen capture. Yes, we have a topic sentence, and yes, we have some facts that are meant to support it. But this is far from a professional piece. Why? A few reasons: first, because the sentence about the Edit and Format menus is somewhat of a tautology; secondly, and more significantly, because the paragraph's details don't clearly show the connection to the main topic, that "working with X is easy"; and thirdly, because the reason why this piece of information is useful or important is totally missing. Now let's look at a rewrite:

"Working with X's interface is easy because you can quickly access the commands and functions you need without having to interrupt the flow of your writing. For example, commands are divided into intuitive menus such as Editing or Formatting that make it easy to find the command that you're looking for.  All menus and toolbars are conveniently located at the top of the screen so you don't have to stop working and hunt for them.

Several other features make it easy to work with the X interface. When you want to navigate through the document, you just use the scroll bars conveniently placed at the side and bottom of the screen. When you want to know exactly where you are in your document, the status area at the bottom of the screen displays information on page number, section, column, etc. By becoming familiar with the interface, you can significantly increase your writing output."

What is the difference between these two versions? The first gives information - the second brings out the significance of the information. The first relates dry facts - the second gives the same facts, but then adds the reasons why those facts are important. The first piece will be glanced at and probably quickly forgotten - the second may spark some appreciation in the reader's mind - which leads to greater understanding of the features that are being explained.

The Goal of a Rhetoric of Technical Writing - Significance
Although all rhetoric has as its primary goal the convincing of an audience, there are goals that are still more specific that characterize different rhetorical situations. For example, in a legal situation, the goals are convincing a judge or jury that a body of evidence supports a particular legal claim. For a scientific article, the goals might be showing that experimental results support a hypothesis or theory.

In technical writing, the rhetorical goals are more modest - they consist of showing that something is significant, i.e., that it has value for the user. This significance ultimately relates to a feature of the product that we are writing about, but more immediately, it can show the significance of a method of doing something, or even of a piece of information. To show that something is significant, our rhetorical argument may include demonstrations, examples, comparisons to previous ways of doing things, explanatory models based on analogy and metaphor, or simply stating the reasons and benefits of the feature itself. Insofar as our writing clearly shows the significance of a feature (or information about the feature), we can consider it successful.

Showing significance is a rhetorical function - it does nothing to alter the facts or its details. But it is an essential ingredient in facilitating understanding - the kind of understanding that a technical manual should further and enhance. True understanding of anything involves appreciating its value and acquiring an intuitive sense of the range of its applicability - ultimately this appreciation translates into greater loyalty to the product itself. This, rather than the mere communication of facts, is the true justification for any piece of technical documentation.

Extreme Editing - A Methodology
How does one go about editing and rewriting information to make it more rhetorically powerful? Here are some steps to follow to help you bring out the significance of a feature and the information about it:

Step One: Find Out the Significance of the Information
Ask yourself why users need to know the information? How do users benefit from the information? You may have to interview others to clarify this point.

Step Two: Find Where the Significance Is Stated in the Piece You're Editing
After you've identified the significance of the information, identify where this significance is indicated in the piece that you're editing. Does it even exist? If it does, is it clear? Does it stand out? Does it enhance the significance of the feature or product itself?

Step Three: Rewrite the Significance in Stronger, Clearer Terms
Strengthen the significance of the feature and the information about it by using a mixed bag of rhetorical tricks (which we've mentioned earlier). Here is where some familiarity with both classical and modern rhetorical theory can be of great value.

Editors and writers who try this will find that their writing is more powerful, more interesting to users, more valuable to the company, and ultimately, more enjoyable to write. This type of writing encourages readers to use features whose significance they may have otherwise missed or underestimated. Ultimately, everyone benefits.

Dr. Mati Schwarcz