Transcript use
IFS410 End User Support Chapter 12 Writing for End Users Technical Writing Documentation is written communication intended to provide support information to end users Goal of technical writing: To produce documents that effectively and efficiently communicate information a reader needs • • Effectively: Readers get the correct information they need to master a topic or perform a task Efficiently: Readers do not have to spend extra time searching for information Good technical writing saves users time Types of User Documents Brochures and flyers Web pages Newsletters Proposals, letters, and memos Handouts and training aids Procedural and operational documentation User guides and manuals Troubleshooting guides Online help systems E-mail and chat messages Technical Writing Differs from Other Writing Differences in Writing style Type of information communicated Organization of document Goals Technical Writing Characteristics Uses an economical writing style Short, simple, declarative sentences, phrases, lists Communicates information vital to a reader’s productivity (just the facts) Uses a style and format that helps readers understand a sequence of events Helps reader with transitions among topics Is brief, but not cryptic (user productivity is goal) Can contain pointers and cross-references A pointer is reference to a location where a reader can locate more information on a topic Use graphical examples to convey concepts. How Technical Documents are Organized Sequential organization follows a step-by-step sequence from first to last • Example: procedural documentation for installation of hardware or software Hierarchical organization flows from top to bottom, and from general information to specific information • Example: online help systems Common Organization for Technical Documents Introduction Purpose of document Who document is intended for Why read the document Body General explanation Specific task steps Common problems users encounter Summary Pointers to additional information Document Planning Who is the target audience? What does the audience already know? What does the audience need to know? What should the audience to be able to do when they finish reading the document? (What’s the goal) How will the document be transmitted to the audience? Help the Audience Target the reading level at 8th or 9th grade Most word processors include a readability index Tell the reader who the intended audience is Organize material so experienced reader can skip basic materials State the purpose of a document in the first few sentences Tell users what tasks they will be able to perform after completing the document Tailor a document to the media Printed: generally longer; help the reader with transitions Online: generally shorter; help the reader with pointers Steps in the Technical Writing Process 1. Generate an idea list 2. Organize the list into a logical outline 3. Expand the outline into a first draft 4. Edit the draft one or more times 5. Arrange for an outside review 6. Revise the draft into its final form 7. Proofread the document Technical Writing Strategies An analogy describes how an unfamiliar concept is similar to a familiar concept Repetition Introduce, explain, summarize Consistent word use Use the same word to refer to a concept Avoid mixing: CD, CD-ROM, compact disc, optical disk Style sheet lists preferences for spelling and word use Example: End user is a noun; End-user is an adjective Consistent verb tense Prefer present tense unless an event clearly occurred in the past Common Problems in Technical Writing Clutter Inappropriate typefaces Gender references Unclear referents Passive voice Nominalization Wordiness Jargon Undefined acronyms Dangling phrases Clutter Use graphics to illustrate a point not just for decoration Use formatting sparingly and consistently only when it helps locate information or understand topic Include considerable white space Use at least 9 point body text Larger for slide shows, brochures, flyers Justified text is Left align most body text aligned at both the Avoid centered and block-justified right and left margins Inappropriate Typefaces Serif typeface includes fine lines (serifs) that project from the top and bottom of a font’s characters frequently used for body text Sans serif typeface does not have serifs often used for titles and headings Specialty typeface is a style of type intended for special use to draw attention to text save for informal use http://psychology.wichita.edu/surl/usabilitynews/81/Pe rsonalityofFonts.htm Gender References Avoid gender-related words unless they clearly fit Avoid: he, she, him, her, s/he Use: they, their, it, he and she, she and he Gender-neutral words are clearer and less offensive Use staffed instead of manned Use chair instead of chairman Use supervisor instead of foreman Can you think of others? Unclear Referents Referent is a word that refers to another word or concept The referent of words such as it, them, and their should be clear Example: The user was using Excel on her HP Pavilion PC to enter a long list of numbers with her voice recognition utility program. Half-way through the list, it froze up. Does it refer to the HP Pavilion PC, Excel, or the voice recognition utility? Or the user? Passive Voice Active voice is a sentence in which the subject performs the action indicated by the verb Example: I prepared the documentation. Use active voice to make text livelier and more interesting Passive voice is a sentence in which the subject receives the action indicate by the verb Example: The documentation was prepared by me. Avoid passive voice Nominalization Nominalization is the use of -tion an -ing endings to create nouns where verbs are easier to understand Example • • Use of nominalization: Perform an installation of the printer driver. Use of verb: Install the printer driver. Wordiness Avoid unnecessary words • Too many words: Prior to the actual installation of the system... • Reduced: Before installing the system... Use short words when possible Use use instead of utilize Use document instead of documentation Use added instead of additional Can you think of other examples? Jargon Jargon words are understood only by those experienced in a field Use simple, direct words that anyone can understand Example: Avoid: Hack the document for the new NIC cards Use: Edit the document for the new network cards If you must use jargon terms, define them first Undefined Acronyms An acronym is a series of letter that represent a phrase Example: RAM is a acronym for random access memory Define the meaning of acronyms for the reader The first time acronym is used, spell out the words then include the acronym in parentheses Example: digital video disc (DVD) Include acronyms in a glossary Tip: Don’t create unnecessary new acronyms Example: Technical Writers Against Unnecessary Acronym Use (TWAUAU) Dangling Phrases A dangling phrase is a word or phrase at the beginning or end of a sentence that adds little meaning Example: The installer will verify that the user’s PC is operational, of course. Avoid a word (or phrase) at the beginning or end of a sentence that adds little meaning to the sentence Eliminate the word (or phrase) or include it elsewhere in the sentence