IFS410 End User Support

Chapter 12

Writing for End Users

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

Technical Writing

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

Types of User Documents

Differences in Writing style Type of information communicated Organization of document Goals

Technical Writing Differs from Other Writing

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.

Technical Writing Characteristics

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

How Technical Documents are Organized

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

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?

Document Planning

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

1. Generate an idea list2. Organize the list into a logical outline3. Expand the outline into a first draft4. Edit the draft one or more times5. Arrange for an outside review6. Revise the draft into its final form7. Proofread the document

Steps in the Technical Writing Process

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

Technical Writing Strategies

Clutter Inappropriate typefaces Gender references Unclear referents Passive voice

Nominalization Wordiness Jargon Undefined acronyms Dangling phrases

Common Problems in Technical Writing

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

Justified text is aligned at both the right and left margins

Clutter

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

Inappropriate Typefaces

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?

Gender References

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?

Unclear Referents

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

Passive Voice

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.

Nominalization

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?

Wordiness

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

Jargon

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)

Undefined Acronyms

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

Dangling Phrases