Chapter 12
Writing for End Users
Learning Objectives
• Types of end-user documentation
• How technical writing differs from other writing
• How technical documents are organized
• How to plan effective user documentation
• The technical writing process
• Effective use of formats
• Technical writing strategies
• Common problems in technical writing
• Tools used in technical writing
• How to evaluate documents
Guide to Computer User Support, 3e
2
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
Guide to Computer User Support, 3e
3
Types of User Documents
• Brochures and flyers • Web pages
• Newsletters
• Proposals, letters, and
memos
• Handouts and training
aids
• Procedural and operational
• User guides and manuals documentation
• Online help systems • Troubleshooting guides
• E-mail and chat messages
Guide to Computer User Support, 3e
4
Brochures and Flyers
• Purpose: primarily promotional
• Intended to catch the eye of the reader and sell an
•
event
Used to advertise
• Staff training sessions
• Open houses
• Computer fairs
• Product demonstrations or availability
• Guest speakers
Guide to Computer User Support, 3e
5
Newsletters
• Purpose: used by support groups to communicate with
•
•
their users
Popular in large companies where support staff does not
regularly come into direct contact with other workers
Can be printed or distributed electronically
Guide to Computer User Support, 3e
6
Handouts and Training Aids
• Purpose: summarize and promote recall of material
•
•
covered in a training session
May be distributed online
Usually short and address a single topic
Guide to Computer User Support, 3e
7
User Guides, Handbooks,
and Manuals
• Purpose: supplement vendor documentation and trade
•
books with information specific to an organization or
computer facility
Structure:
• Tutorial format is a document organization style
which guides a user step-by-step to hardware or
software features
• Reference format is a document organization style
in which all material on a topic is in one location
• Combination format – tutorial plus reference
Guide to Computer User Support, 3e
8
Online Help Systems
• Purpose:
• provide convenient access to information for users
• replace or supplement printed materials
• Information presented must be succinct
• Use of hypertext links and index searches provide
•
•
powerful tools to locate needed information quickly
Increasing in popularity and convenience
Not all users are comfortable with online materials
Guide to Computer User Support, 3e
9
E-mail and Chat Messages
• Purpose: formal and information online communications
• with external clients and vendors
• with internal end users and work colleagues
• Projects an image of the organization and support
•
•
specialist
Should reflect good technical writing skills
Growth in use of these communications emphasizes the
need for excellent writing skills for user support
specialists
Guide to Computer User Support, 3e
10
Web Pages
• Purpose: make support materials available on the
•
•
•
•
Internet
Need to be organized and written so that users can locate
information quickly and easily
Must be very short, but contain hypertext links that lead
users to additional information
Image of organization is at stake in Web documents
Challenge is to keep Web-based support information
current and accurate
Guide to Computer User Support, 3e
11
Proposals, Letters, and Memos
• Purpose: organizational correspondence accounts for a
significant portion of computer use
–Proposals
–Letters
–Memos
–Needs assessment reports
–Performance appraisals
–Other correspondence
• Ability to produce basic business correspondence is an
important user support skill
Guide to Computer User Support, 3e
12
Procedural and Operational
Documentation
• Purpose: written procedure steps and checklists intended
•
primarily for internal organizational use
Examples
• Preparation of problem reports in a help desk environment
• Documentation of hardware or software installation
•
procedures
Site Management Notebook (see chapter 10)
Guide to Computer User Support, 3e
13
Troubleshooting Guides
• Purpose: help end users solve computer problems
• Examples
• Problem-solving section in User Guide
• FAQ on frequent problems users encounter
• Script on incident handling procedures
• Problem report in Help Desk knowledge base
• Must be clear, concise, and well written
Guide to Computer User Support, 3e
14
How Technical Writing Differs from
Other Writing
• Differences in
• Writing style
• Type of information communicated
• Organization of document
• Goals
Guide to Computer User Support, 3e
15
Technical Writing Characteristics
• Uses an economical writing style
• Short, simple, declarative sentences, phrases, lists
• Communicates information vital to a reader’s
•
productivity
Uses a style and format that helps readers understand a
sequence of events
• Helps reader with transitions among topics
• Is brief, but not cryptic
• Can contain pointers and cross-references
• A pointer is reference to a location where a reader can locate
more information on a topic
Guide to Computer User Support, 3e
16
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
Guide to Computer User Support, 3e
17
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
Guide to Computer User Support, 3e
18
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?
How will the document be transmitted to the audience?
Guide to Computer User Support, 3e
19
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
Guide to Computer User Support, 3e
20
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
Guide to Computer User Support, 3e
21
Step One: Generate an Idea List
• Brainstorm is a technique to generate a list of potential
•
topics
Tip: During brainstorming, don’t worry about whether a
topic is
• major or minor
• useful or not
• high or low priority
Guide to Computer User Support, 3e
22
Step Two: Organize the Idea List
Into an Outline
• Arrange topics into logical sequence
• Identify major and minor topics
• Cut and paste to try out different sequence of ideas
• Use a word processor’s outline feature as a tool
• The final organization should answer the question:
• In what order does the reader need to know this
information?
Guide to Computer User Support, 3e
23
Step Two: Organize the Idea List
into an Outline
• Paragraphs with topic sentences
• Transitions between paragraphs and sections
• Define terms
• Formats
•
•
•
Style elements: fonts, capitalization, centering, indentation,
underlines, bullets and numbered lists help a reader understand the
structure
Format consistency: style sheets and templates in word processors
help insure consistent use of style elements
Lists and tables: use instead of long narrative passages to help a
reader locate information needed quickly
Guide to Computer User Support, 3e
24
Step Four: Edit the Draft
• Eliminate extra words
• Perform a format consistency check
• Consistent use of fonts for headings, subheadings, centering,
boldface, italics, and underlining
• Perform a technical accuracy check
• A test of any procedural or technical steps
• Eliminates errors in instructions
• Check URLs to eliminate dead links
Guide to Computer User Support, 3e
25
Step Five: Get an Outside Review
• Purpose:
• Raise questions about contents
• Spot inconsistencies
• Find unclear meaning
• Identify poor writing techniques
• Locate other problems that the writer is too close to
the document to see
Guide to Computer User Support, 3e
26
Step Six: Revise the Draft
• Incorporate revisions into document
• When an edit pass results in marginal improvements,
consider it done
Guide to Computer User Support, 3e
27
Step Seven: Proofread the Draft
• Final pass through a document prior to publication
• Look for
• Inconsistent capitalization and punctuation
• Inconsistent font use
• Extra spaces between words and sentences
• Incorrect page breaks
Guide to Computer User Support, 3e
28
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
Guide to Computer User Support, 3e
29
Sample Page from a Style Sheet
Guide to Computer User Support, 3e
30
Technical Writing Strategies (continued):
Parallel Structure
• Parallel structure treats similar items consistently
throughout a document.
Guide to Computer User Support, 3e
31
Common Problems
in Technical Writing
• Clutter
• Inappropriate typefaces
• Gender references
• Unclear referents
• Passive voice
Guide to Computer User Support, 3e
• Nominalization
• Wordiness
• Jargon
• Undefined acronyms
• Dangling phrases
32
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
Justified text is
•
Larger for slide shows, brochures, flyers
Left align most body text
•
aligned at both the
right and left margins
Avoid centered and block-justified
Guide to Computer User Support, 3e
33
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
Guide to Computer User Support, 3e
34
Example Typefaces
Which is most readable?
Guide to Computer User Support, 3e
35
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?
Guide to Computer User Support, 3e
36
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?
Guide to Computer User Support, 3e
37
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
Guide to Computer User Support, 3e
38
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.
Guide to Computer User Support, 3e
39
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?
Guide to Computer User Support, 3e
40
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
Guide to Computer User Support, 3e
41
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)
Guide to Computer User Support, 3e
42
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
Guide to Computer User Support, 3e
43
Technical Writing Tools
• Outliner
• Spell checker
• Custom dictionary
• Thesaurus
• Grammar checker
• Readability index
• Desktop publishing features
• Collegiate dictionary
Guide to Computer User Support, 3e
44
Document Evaluation Criteria
(Overview)
• Content
• Organization
• Format
• Mechanics
Guide to Computer User Support, 3e
45
Content
• Is the information accurate?
• Is the coverage of the topic complete?
Guide to Computer User Support, 3e
46
Organization
• Is the information easy to locate?
• Are the transitions between topics identifiable?
• Can the user get in and out quickly with the right
answer?
Guide to Computer User Support, 3e
47
Format
• Does the layout help guide the reader?
• Is the format consistent?
Guide to Computer User Support, 3e
48
Mechanics
• Are words spelled correctly?
• Is it grammatical?
• Is the writing style effective?
Guide to Computer User Support, 3e
49
Chapter Summary
• User support staff write a variety of different types
•
•
•
of documents to communicate with end users,
coworkers, vendors, and managers
The goal of technical documents is to effectively
and efficiently communicate information needed by
the reader
Technical writing begins by defining the
characteristics of the target audience and the task
the writer wants the reader to be able to do
Technical writing uses short words and sentences
and an organization that helps the reader locate
information
Guide to Computer User Support, 3e
50
Chapter Summary (continued)
• The technical writing process includes
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
• The layout of a document and formatting help the
•
reader to understand the organization and
transitions between topics
Successful writers use analogies, repetition,
consistent work use and parallel structure
Guide to Computer User Support, 3e
51
Chapter Summary (continued)
• Successful writers avoid clutter, hard-to-read typefaces,
•
•
gender references, passive voice, unclear referents,
wordiness, jargon, and acronyms
Software tools that aid writers include an outliner, spell
checker, thesaurus and grammar checker
Four criteria to evaluate technical documents are
• Content
• Organization
• Format
• Mechanics
Guide to Computer User Support, 3e
52