Chapter 12 Writing for End Users 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 Newsletters Handouts and training aids User guides and manuals Online help systems E-mail and chat messages Web pages Proposals, letters, and memos Procedural and operational documentation Troubleshooting guides

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 Most word processors include a readability index 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 to illustrate a point not just for decoration 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 Left align most body text Avoid centered and block-justified Justified text is aligned at both the 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/PersonalityofFonts.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 Use short words when possible 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