Developing Quality Technical Information Ch05 Clarity

103 Chapter5 Clarity Easy reading is damn hard writing. —Nathaniel Hawthorne Clear information is information that users can understand the first time. They don’t need to reread it to untangle grammatical connections, sort out excess words, decipher ambiguities, figure out relationships, or interpret the meaning. Clarity in technical information is like a clean window through which you can clearly see the subject. The first time that most writers try to write about something, words don’t tumble out clearly. Often, to break through a block, writers write as if they were speaking, but this approach introduces problems such as unnecessary words, vague referents, and rambling sentences. People can get visual and auditory cues when you’re speaking, but written words are on their own to convey a message. Clear information is mainly the result of rewriting—replacing, adding, and deleting parts to achieve clarity. Clear information requires close attention to elements such as words, phrases, sentences, lists, and tables to make sure that each participates appropriately in the message. This attention is proba- bly more helpful when you are rewriting than when you are first writing. 104 Developing Quality Technical Information Easy to understand Clarity provides the rationale for many decisions about style and for some decisions about visual effectiveness. You might choose, for example, bold- face for certain uses of words and italics for certain other uses; consistently applying these style decisions enhances clarity by making information eas- ier for users to understand the first time. Guidelines for achieving clarity in technical writing have traditionally been based on experience and on studies with native speakers of English, particu- larly American English. However, because of the explosion of technical information on the Web and the increased use of technical information throughout the world, technical writers must be sensitive also to the needs of an international audience for clear English. Aspects of clarity also overlap aspects of completeness (especially relevance and too much information) and organization (especially consistency and sub- ordination). Clear information requires a strong focus on what users need to know and when they need to know it. Extraneous information muddies the message. Relationships among pieces of information (whether in sentences, lists, tables, or some other element) must be clear. To make information clear, follow these guidelines: � Focus on the meaning. � Avoid ambiguity. � Keep elements short. � Write cohesively. � Present similar information in a similar way. � Use technical terms only if they are necessary and appropriate. � Define each term that is new to the intended audience. 105 Clarity Focus on the meaning Clear information requires that you focus on what you want to say. What’s the point? What do you want the users to do or to know? When most people write, they need to warm up to a subject. They need to write a while before the words flow and they see what they need to say. A first pass can produce long sentences, imprecise words, unnecessary modifi- ers, and rambling paragraphs. Consider how you would focus on the meaning in the following paragraph, which gives an overview of a product for storing and retrieving image data: Each sentence has over 25 words, but are they all needed? Does each word contribute to the meaning? In an inflated economy people must spend lots of money for everyday items such as groceries or a tank of gas; in this “inflated” passage users must read many more words than the message warrants. Contributors to the word inflation in this paragraph are: Imprecise words “now has plans to,” “makes use of,” “kinds of” Intensifying words “basically,” “significantly,” “very,” “specifically,” “really,” “some,” “any” Original A major company maintains a large personnel database that it basically makes use of for many kinds of employee-related applications such as payroll and benefits. The company now has some plans to extend the database sig- nificantly to include current photographs of employees and use the photo- graphs as the basis for a very modern security system. The system is specifically designed to protect secure areas of the company’s building from access by any people who really do not have authorization to be there. 106 Developing Quality Technical Information Easy to understand When you revise the passage to remove these, you get: This revision is clearer, but the passage is still not as clear as it could be. Many of the nouns are modified, but only a few modifiers are needed: � “Major” and “large” do not supply useful information in this situation; in fact, they detract from the meaning by limiting the example unneces- sarily. Unfortunately, the emphasis in the first part of the sentence falls on these modifiers, as you will find if you read the sentence aloud. � You don’t need “many” as a modifier of the applications if you also have the examples of applications. � “Current” is not needed because in this context you can take for granted that the photographs should be up to date. � “Modern” introduces a judgment that is probably not needed in a para- graph that is not intended for marketing the product. � “Secure” as a modifier of “areas” is confusing because the areas won’t be secure unless they are protected. � “Company’s” is superfluous because the context should make clear that the building is the one associated with the company. � The modifier of “access” is a long phrase that you can shorten just to “unauthorized.” When you remove the unnecessary modifiers, you get: By focusing imprecise words and removing intensifying words and unnec- essary modifiers, you reduce the length of the paragraph by around a third. Now the meaning is clearer, but you can make it even clearer by removing extraneous information. In this context users care that the company is First revision A major company maintains a large personnel database that it uses for many employee-related applications such as payroll and benefits. The company plans to extend the database to include current photographs of employees and use the photographs as the basis for a modern security system. The sys- tem is designed to protect secure areas of the company’s building from access by people who do not have authorization to be there. Second revision A company maintains a personnel database that it uses for employee-related applications such as payroll and benefits. The company plans to extend the database to include photographs of employees and use the photographs as the basis for a security system. The system is designed to protect certain areas of the building from unauthorized access. 107 Clarity extending the database for image data but not that the company maintains the database or uses it for many employee-related applications. The first sentence eases into the subject, but it is not needed for clarity. When you remove the extraneous information, you get: The revised paragraph focuses on the company and the relationship between the personnel database, employee photographs, and the security system. The revised paragraph has only two sentences. You might find that you have more that you want to say in this paragraph. Perhaps, you could men- tion the product as a way of storing and retrieving the photographs in the database. Some writers believe that a good paragraph should have at least three sen- tences—one to introduce the subject, one to develop the subject, and one to summarize the additional information and lead into a new subject. Such a formula for a paragraph can help you think through the information that’s appropriate for a paragraph. However, the formula should not result in extra sentences that get in the way of the message. Clarity is better served by a short paragraph than by one with extra sentences. Short paragraphs help users scan and read information online, including on the Web. People are likely to skip long or difficult paragraphs, and so they might miss information that they need. When you focus on what you want to say, you can fix many clarity prob- lems, especially: � Imprecise words � Overuse of intensifying words � Long sentences � Unnecessary modifiers � Rambling paragraphs Make every word count. Eliminate words that do not contribute to the meaning. Third revision A company plans to extend its personnel database to include employee pho- tographs. The company wants to use the photographs in a security system that will protect certain areas of the building from unauthorized access. 108 Developing Quality Technical Information Easy to understand As you can see in the following list, an imprecise verb depends on a word or two after the verb to give it meaning. For example, in the combination “have plans,” the verb have suggests nothing about planning, and the sense of plan- ning has moved to the object of the verb. Information is clearer when a verb conveys the action. Imprecise verbs Precise verbs be in agreement agree be capable of can carry out an inspection of inspect conduct an investigation of investigate do a verification of verify draw a conclusion infer, conclude give an answer answer give rise to cause have a requirement require have knowledge of know have plans plan have the capability to can hold a meeting meet keep track of track make a distinction distinguish make a proposal propose make a suggestion suggest make changes to change make contact with meet perform the printing print provide assistance help reach a decision decide render inoperative break serve to define define show improvement improve 109 Clarity In addition to making some verbs more precise, you might be able to elimi- nate some words, such as: Such words are meant to intensify the meaning, but you’ll probably find that the meaning is clearer without them. In speaking, people tend to use these words liberally, but in writing, these words quickly lose their effect. When you consider using an intensifying word, try the sentence in your mind with and without the intensifying word; think about the effect on the meaning of the sentence and surrounding sentences. When you rewrite a sentence or a paragraph, consider how each word con- tributes to what you want to say. Question whether all the words in a long sentence are needed, and even whether the sentence is needed. absolutely completely particularly simply actually definitely perfectly some any fairly quite specifically basically just really totally certainly of course significantly very 110 Developing Quality Technical Information Easy to understand Avoid ambiguity This guideline could be called “Have mercy on translators and nonnative speakers.” These people are more likely than native speakers to have diffi- culty when information is ambiguous. Writing for an international audience is especially necessary for material that people access on the Web. English is the native language of less than half of Internet users, although around 85% of Web pages are in English. A third of Internet users primarily speak a European language, and around a quarter primarily speak an Asian lan- guage. To avoid ambiguity in what you write, follow these guidelines: � Use words with a clear meaning. � Avoid vague referents. � Place modifiers appropriately. � Avoid long strings of nouns. � Write positively. � Make the syntax of sentences clear. Use words with a clear meaning Words that have more than one meaning can be confusing when more than one meaning fits the context. Some ambiguous words are small but impor- tant in conveying information about relationships between clauses. Problems arise when words such as since, once, as, and while could indicate either time or something else, such as cause or contrast. Consider the use of since in the following sentence: A native speaker would probably recognize that since in the original sen- tence applies to cause rather than time. However, using the unambiguous word (as in the revision) is safer than relying on the context to help users make the correct choice. Original Revision Since you created the table, you have authority to change the table. Because you created the table, you have authority to change the table. 111 Clarity Because of the richness of the English language, the words that you choose will probably have more than one meaning. However, you can reduce the confusion over which meaning a word has in a particular context by using the word consistently with only one of its meanings. For example, use “replace the part” to mean only “put the part back” and not also “substitute a new part for the one that you have.” The following list shows some words that are likely to be ambiguous and some words to use instead: May and can are confusing when they are used interchangeably in technical information. As a child, you probably learned to use may when asking for permission. In technical information, may rarely has the meaning of permis- sion but is sometimes used ambiguously to indicate possibility or capability, as in the following sentence: Does this sentence mean that the user can restrict the use of the commands or that the user might do so from time to time? A user cannot know, unless the writer has used may and can conscientiously in the surrounding informa- tion and thus prepared the user for the intended meaning here. Do not use may and can interchangeably. Reserve may for the possibility of doing something and can for the ability to do it. In technical information, capability is usually more appropriate to write about than possibility. Might indicates a greater degree of uncertainty about a possibility and so indicates possibility less ambiguously than may does. You could choose to use might rather than may in many sentences that deal with possibility. Ambiguous Clear as because as long as if in spite of regardless of, despite may can, might once after, when on the other hand however, by contrast since because through finished while although, whereas You may restrict authority to issue certain commands. 112 Developing Quality Technical Information Easy to understand A word that can be used as more than one part of speech can be confusing when the word is used in two different ways close together or when it is used with other such words. For example, each of the following words can be used as a verb or as a noun: Consider the following sentences: The first sentence puts the same word at opposite ends of the sentence, first as the verb and then as the noun. The second sentence puts the noun and the verb next to each other. Each revision keeps the noun but changes the verb. Two possible verb changes are shown for the second sentence. In general, the use of a word as a verb offers more opportunities for synonyms and paraphrases than does the use of a word as a noun. For example, if the verb record should have a less formal sense than register, you could use write or remember instead. Each of these examples is one sentence, but you need to watch for possible confu- sion in such words also when they are in the same paragraph or in the same topic. In the following sentence, the nouns are hard to distinguish from the verb: change document process team design function record work Original Record the date of the record. The timer function functions to stop certain actions. Revision Register the date of the record. The timer function serves to stop certain actions. The time function stops certain actions. Original Revision The team documents design changes. The members of the team document the changes in the design. 113 Clarity The revision inserts articles before the nouns (changes and design) and expands the noun string (design changes), making the verb (document) more obvious. The change in the subject to members of the team also helps reduce the possible interpretation that team modifies document. Use words that have clear meanings. Look for other ways that words might be misunderstood, particularly by nonnative speakers of English. Avoid vague referents Another clarity problem for translators and nonnative speakers is vague ref- erents. Sometimes when writers use a pronoun to refer to a noun, the noun is vague for any of these reasons: � It is far from the pronoun, perhaps in another sentence. � It is among other nouns that might fit as the one being referred to. � It is not stated explicitly. Consider the vague referent in the following passage: The original passage is confusing because you’re not sure whether it refers to InfoGrammar or to the target file system. Is the referent the subject of the preceding sentence or the noun that immediately precedes the pronoun? The revision specifies database, clarifying the referent without repeating it. Consider the referents for the pronouns each and one in the following sen- tence: Original Revision InfoGrammar is a virtual database that you can create from the target file sys- tem. It consists of a set of statements that provide input to the projection utility. InfoGrammar is a virtual database that you can create from the target file sys- tem. This database consists of a set of statements that provide input to the projection utility. Original You can have multiple catalogs for a single source; however, each can access only one. 114 Developing Quality Technical Information Easy to understand In the original sentence, the referents for each and one are not clear. Native speakers might guess correctly what these words refer to, aided by the order of the nouns in the first clause. However, even native speakers waste time considering whether the clause might mean that “each source can access only one catalog.” A pronoun such as it, this, or that at the start of a sentence can cause confu- sion, as in the following passage: The original passage refers to a noun that is only implied in the preceding sentence. The revised passage replaces the pronoun with a noun phrase (“having your own copy”). Check that the antecedents for the pronouns that you use are clear. Also, the style guideline “Use correct grammar” on page 183 discusses some pronoun errors to be aware of as you write or edit. Place modifiers appropriately Modifiers include prepositional phrases and relative clauses, as well as adjectives and adverbs. Modifiers that are placed inappropriately cause con- fusion, as in the following sentence: Revision You can have multiple catalogs for a single source; however, each catalog can access only one source. Original Revision Copy this file so that you can edit and save your version locally. This is espe- cially important when InfoProduct is installed on a network and you want to run a customized version of the product. Copy this file so that you can edit and save your version locally. Having your own copy is especially important when InfoProduct is installed on a network and you want to run a customized version of the product. Original Click the configuration server to which you want to link the list manager serv- ers in the Configure Server Name field. 115 Clarity The phrase “in the Configure Server Name field” is out of place. That field is not where the linking occurs. Instead, that field has the names of the config- uration servers, and so you might revise this sentence as: Now you have another problem of a misplaced modifier. The that clause should modify “configuration server” and not the field, which the restrictive clause is next to. You have two choices, as in the following revision: Depending on the context, you could choose to put the intervening phrase in parenthes