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