Conversational Maxims and Technical Documentation: Using a Tool from Linguistics in Technical Writing

By Joseph Devney | STC Fellow

You are lost. You see a man walking down the sidewalk, and tell him your plight. Can he offer directions?

“Three blocks down, turn left onto California Street. A couple of blocks up, you will see it on your left. Big Art Deco building. You can’t miss it.”

You thank him, go on your way, and arrive at the right place in a few moments.

But why did you trust the information? He could have been mistaken. He could have been lying. He may not have given you all the information you needed. His directions may have been vague or ambiguous. You trusted him because that is the way humans typically interact. We assume that everyone in the conversation is trying to be cooperative, unless we have reason to think otherwise. And this assumption is usually true.

But what does “cooperative” mean here? A philosopher of language, Paul Grice, gave a formal description, spelling out four “maxims of conversational cooperation.” Before I address the maxims in detail, let me explain why they are relevant to technical communication.

The conversation described above is a discourse. That is, some example of language use that is more than a single sentence. This broader term includes technical documentation of all kinds. Usability consultant Ginny Redish says that writing is an “asymmetric conversation.” In linguistic terms, a user manual or a help file is an asymmetric discourse. The company is telling the customer about the product and how to use it, but the customer has little opportunity to talk back. Still, it is a discourse, and the linguistic tools for discourse analysis can be applied.

The Maxims

Grice identified four characteristics of how people engage in conversation: the maxims of conversational cooperation, often called the Gricean maxims.

• The Maxim of Quantity: Be as informative as you can. Give as much information as is needed and no more.
• The Maxim of Quality: Try to be truthful. Do not give information that you know to be false or that is not supported by evidence.
• The Maxim of Relevance: Try to be relevant. Say things that are pertinent to the discourse, at that point in the discourse.
• The Maxim of Manner: Try to be as clear, brief, and orderly as you can in what you say. Avoid ambiguity. Avoid obfuscation.

These maxims are not rules we learn in school. They are the result of Grice observing and analyzing interactions between people. These are the rules he deduced that people follow unconsciously when they interact with others. If everybody follows the maxims—or deviates from them only for accepted reasons, like humor or politeness—you get effective communication.

The Maxims in Discourse Analysis

People don’t always follow the maxims. For a linguist analyzing some example of communication, the violation of one of the maxims might be significant. Could it be a sign of deception? Or disrespect? Or something else other than cooperation?

A man was trying to obtain an election ballot in someone else’s name. But he was careful not to say anything untrue. He asked the poll worker, “do you have a [name of a deceased voter] on your list?” She did, and read out the address to confirm he was the right person. “That’s the address,” he replied. “The address.” Not “my address,” because that would be explicitly untrue. Not “his address,” because that would give the game away. He went for ambiguity: He and the poll worker had different ideas of what “the address” meant—but only he knew that.

Discourse analysis revealed the deception.

But in everyday interactions, violating a maxim can be innocuous. Here is a quick example. I am in a restaurant. I say to the waitress, “Do you have a dessert menu?” On the surface, this is a request for information, a yes-or-no question. But why would I care if she had one or not? The waitress quickly reinterprets my question to be the imperative: “Give me your dessert menu.” This sort of thing happens all the time.

The Maxims in Technical Discourses

Help files, marketing literature, system administrator manuals, websites, installation instructions—these are all discourses, in the linguistic sense. We can use the Gricean maxims to determine whether they are doing their job. Can the reader accept the content without worry?

As mentioned above, people sometimes violate the maxims. Often what happens is that a different meaning is intended than what it seems to be. In normal conversation, that is okay. Because the Gricean maxims generate implicatures. If the literal meaning of an utterance doesn’t make sense in context, we automatically look for a way to make it relevant. We depend on the implicatures.

But that is not the case for technical writing. For technical writing, do not depend on implicatures. To quote linguist Roger Shuy: “A cardinal rule of comprehension is that the writer should not cause the reader to have to infer the intended meaning.” Be explicit.

Let’s look at the maxims in detail in relation to technical documentation.

The Maxim of Quantity

“Be as informative as you can. Give as much information as is needed, and no more.” I see this maxim violated in technical documentation fairly often, especially if it is not produced by professional technical writers. Maybe you have seen this kind of “name field documentation,” as I have heard it called.

This list appeared immediately below an image of the dialog box being explained. You could eliminate the numbers and the explanations without losing any information. In fact, you could delete the list entirely without losing any information, since the dialog box pictured is self-explanatory.

The Maxim of Quality

“Try to be truthful. Do not give information that you know to be false, or that is not supported by evidence.” Violations of this maxim are not a big problem in technical communication. Companies rarely want to lie to their customers. But that phrase, “not supported by evidence,” is important. This can become an issue when marketing-type hyperbole turns up in technical documentation.

Have you ever seen technical documentation that introduced a product or a feature by saying it is “powerful?” That would be a pretty subjective judgement. How is “powerful” defined?

Or have you seen expressions like “generating a profit and loss statement is simple”? What evidence do they have that any particular user will think that the task is simple? Quite possibly none. That is just the marketing message.

Technical documentation used to describe or explain a product or a procedure is not the place for unsupported value judgements.

The Maxim of Relevance

“Try to be relevant. Say things that are relevant to the discourse.“ I once had to help introduce a new version of Microsoft Windows to a large corporation. The consultant they brought in to run the rollout had not worked with technical writers before. He gave us a book published by Microsoft about the new OS that he thought was great. It didn’t actually explain the interface. It was mainly biographies of the personas that the team working on it had created. Personas are a useful tool for designing a product, but irrelevant to me or to the audience that I was writing for.

If you have worked with the DITA standard, you know something about the issue of relevance. In DITA, you are required to make a distinction between concept information and task information. You cannot mix the two. This is a way of enforcing relevance, so you don’t add conceptual information in the middle of a set of procedural steps.

Another problem that I have seen multiple times is including the history of the company or the technology in technical and instructional content. This information is not important to people who turn to the documentation, because they want to get a specific job done.

The Maxim of Manner

“Try to be as clear, brief, and orderly as you can in what you say. Avoid ambiguity. Avoid obfuscation.”

Clear. Brief. Orderly.

No ambiguity. No obfuscation.

This maxim is the one most broadly applicable to technical writing—and to technical communication in general. These are our preeminent goals.

You want clarity. Look through your text. Is there anything that could be misinterpreted? Anything that might not be clear to the intended reader?

Here are a few potential problems. You can add to the list.

• Do you use the word should? Watch out for that one. It adds ambiguity.
• Check for “garden-path” sentences. These sometimes show up when you leave out an optional “that.”
• Avoid vague words.
• Avoid using slashes. A slash connecting two words can be interpreted in multiple ways. And? Or? Two words for the same thing?
• Do you have repetitive definitions or explanations? That is, paragraphs almost identical except for a word or two in the middle?

For technical documentation, one aspect of being orderly is being consistent. Do you always use the same term for the same referent? Not doing so leads to obfuscation. You can confuse the reader. I once read something written by a software engineer in which he referred to the same short string of code as a function, a routine, and an API—all in the course of two consecutive sentences.

To avoid things like that, technical writers sometimes have to be the word police. You might want to create a word list to ensure you get it right throughout a document or suite of documents.

Putting the Maxims to Work

Four maxims, four questions, four things to look for in your documentation. Make sure you are being cooperative in your conversation with your audience.

The Gricean maxims have been used for years to help linguists analyze conversations, speeches, narratives, and other types of discourse. More recently, forensic linguist Roger Shuy has used them to help analyze warning labels, product package inserts, and other types of technical communication. I think that their potential applications in our field are much broader. If you do put them to use, please let me know about your work.

References

Grice, Paul. Studies in the Way of Words. Cambridge, MA: Harvard University Press, 1991.

Redish, Ginny. “Writing as an Asynchronous Conversation.” Presented at the Society for Technical Communication Summit & Expo, 2008. http://stc-access.org/wp-content/uploads/sites/3/2014/01/writing_as_an_asynchronous_conversation.pdf

Shuy, Roger. Fighting Over Words: Language and Civil Law Cases. New York, NY: Oxford University Press, 2008.

JOSEPH DEVNEY (joe@devney.com) is a technical writer and a linguist, and has taught both linguistics and technical communication at the college level. His work as a linguist includes research into improving jury instructions (which he sees as a technical writing task) and analyzing a police interview for a criminal trial. He has been a technical writer since the mid-1990s, working in a variety of industries. His STC history includes four years judging the International Technical Art Competition, serving as President and (currently) VP for Programs of the Berkeley community, and being awarded the rank of Fellow. He also does public speaking in both fields, for both specialist and general audiences.