ch11x

birthdaytestΤεχνίτη Νοημοσύνη και Ρομποτική

17 Νοε 2013 (πριν από 3 χρόνια και 8 μήνες)

74 εμφανίσεις

CHAPTER 11

Writing for End Users

1

CTS 217: Computer Training & Support

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


Strategies for technical writing


Common problems in technical writing


Tools used in technical writing


How to evaluate documents

2

Technical Writing


Documentation

is written communication
intended to provide support information to end
users


QR

sheets, online assistants, FAQ, ReadMe files


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

3

Types of User Documentation


Brochures and flyers


Newsletters


Handouts and
training aids


User guides, h/b, and
manuals


Online help systems


E
-
mail and chat
msg


Web pages


Proposals, letters, &
memos


Procedural and
operational
documentation


Troubleshooting
guides


4

Brochures and Flyers


Purpose: primarily promotional


Catch reader’s eye (Design!)


“Sell” event


Used to advertise


Staff training sessions


Open houses


Computer fairs


Hardware and software product demonstrations or
availability


Guest speakers

5

Newsletters


Purpose: used by support groups to
communicate with their users


Multiple columns,
pics
, diagrams, charts


Tips and tricks


Popular in large companies where support
staff does not regularly come into direct
contact with other workers


Can be printed or distributed electronically

6

Handouts and Training Aids


Purpose: summarize and promote recall of
material covered in a training session


May be distributed online


FAQ (How do I…)


PowerPoint handouts in online courses


Usually short and address a single topic

7

User Guides, H/books, & Manuals


Purpose: supplement vendor documentation and
trade books with information specific to an
organization or computer facility


Handbook for computer use at a university


How to install and use products (QS guide)


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


Probably better for experienced users


Combination format


tutorial plus reference

8

Online Help Systems


Purpose:


provide convenient access to information for users


replace or supplement printed materials


Information presented must be concise


Use of hypertext links and index searches provide
powerful tools to locate needed information
quickly


Troubleshooters in Windows


Increasing in popularity and convenience


Not all users are comfortable with online
materials

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


Use correct grammar and spelling!!


Netiquette


http
://owl.english.purdue.edu/owl/resource/636/01

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


Too easy to visit another site


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


WorstOfTheWeb.com &
Basic Design Site

11

Proposals, Letters, & 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

12

Procedural and Operational Doc.


Purpose: written procedure steps and checklists
intended primarily for internal organizational use
(may enjoy this type of writing
J
)


Examples


Preparation of problem reports
in a help desk environment


Documentation of hardware or
software installation procedures


Unclear = wastes time,
escalates frustration, hinders
productivity

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


Next


look at differences in types of writing

14

How Technical Writing Differs
from Other Writing


Differences in


Writing style


NOT a research paper


Type of information communicated


Goals


Style


Organization of document

15

Technical Writing Characteristics


Uses an economical writing style


Short, simple, declarative sentences, phrases, lists


Simple, compound, run
-
on sentences p. 499


NOT entertaining


Communicates most important point at
beginning of topic


Uses a style and format that helps readers
understand a sequence of events


Example 2 on p. 499

16

Technical Writing Characteristics


Is brief but not cryptic


Cover essentials clearly and effectively


Can contain pointers and cross
-
references


A
pointer

is reference to a location where a reader
can locate more information on a topic


Goal: not to entertain, leave out humor and
fancy words

17

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


Use combination

18

Common Org. for Tech Docs


Introduction


Purpose of document


Who document is intended for (audience)


Not waste time


Why read the document


Body


Gen
inf
; specific task steps


Include MAIN points only


Common problems users encounter


Summary


Review; additional information?

19

Document Planning


Similar to those for training session


Who is the target audience?


Their level of expertise


Reading level: target 8
th

or 9
th

grade (readability
stats)


What does the audience already know?


Their
bkg
;
stmt

in Intro; might skip your doc


Section headings for basics so exp.
u
sers can skip

20

Document Planning


What does the audience need to know?


Define purpose of document


What should the audience to be able to do
when they finish reading the document?


Specific task should be accomplished after they
read it/follow steps


How will the document be transmitted to the
audience?


Print? Online? Transitions, hyperlinks to guide

21

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

8. Proofread the document AGAIN!

22

Step 1: 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


After brainstorm: prioritize,
reorganize, refine

23

Step 2: Organize the List Into an
Outline


Arrange topics into logical sequence


Identify major and minor topics


Cut and paste to try out different sequences
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?

24

Step 3: Expand Outline into 1
st

Draft


Paragraphs with topic sentences


Transitions between paragraphs and sections


As a result, for example, first, next, finally


Define terms


Bold face


Formats (Do not overdo it!!)


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

25

Step 4: Edit the Draft


Eliminate extra words


Example on p. 507


Perform a
format consistency check


Consistent use of fonts for headings, subheadings,
centering, boldface, italics, and underlining


WP software helps with this


Perform a
technical accuracy check


A test of any procedural or technical steps


Eliminates errors in instructions


Check URLs to eliminate dead links

26

Step 5: 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


Analogous to beta testing a training module


Don’t be defensive!

27

Step 6: Revise the Draft


Incorporate revisions into document


When an edit pass results in marginal
improvements, consider it done


Perfectionist? Know when to stop

28

Step 7: 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


May show as grammar error in Word


Incorrect page breaks

29

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


NOT worried about variety (synonyms)


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 (p. 512)

30

Sample Page from a Style Sheet

31

Technical Writing Strategies (cont.)


Parallel structure
treats similar items
consistently throughout a document.


Titles, headings, subheadings


Verb tenses and parts of speech


Bulleted lists

32

Common Problems in Technical
Writing


Clutter


Inappropriate
typefaces


Gender references


Unclear referents


Passive voice


Nominalization


Wordiness


Jargon


Undefined acronyms


Dangling phrases


33


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 (easiest to read)


Avoid centered and block
-
justified

Justified

text

is

aligned

at

both

the

right

and

left

margins
.

34

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

35

Example Typefaces

Which is most readable?

36

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

37

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
DC7900 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 PC, Excel, or the voice
recognition utility?

38

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


Table 11
-
1 on p. 516


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

39

Nominalization


Nominalization

is the use of
-
tion

and
-
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.


Table 11
-
2 on p. 517

40

Wordiness


Avoid unnecessary words


Too many words: Prior to the actual installation of
the system...


Reduced: Before installing the system...


Table 11
-
3 on p. 517


Use short words when possible


Use
use

instead of
utilize


Use
document

instead of
documentation


Use
added

instead of
additional

41

Jargon


Jargon

words are understood only
by those experienced in a field


Use simple, direct words that anyone can
understand


Examples:


Avoid: Hack the document for the new NIC cards


Use: Edit the document for the new network cards


Start
-
up process = power
-
on step


If you must use jargon terms, define them first

42

Undefined Acronyms


An
acronym

is a series of letters 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)

43

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


Examples & web site on p. 518
-
519

44

Technical Writing Tools


Outline tool


Spell checker


Custom dictionary


Thesaurus


Grammar checker


Readability index


Desktop publishing features


Collegiate dictionary (m
-
w.com)

Read critically. What

makes it good or bad?

45

Document Evaluation Criteria


Content


Relevant,
accurate

information


Complete coverage of
topic


Organization


Easy to locate info


Clear transitions


Find answers quickly



Format


Layout guide reader


Consistent format


Mechanics


Spelling


Grammar


Effective writing style

46

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

47

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

48

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

49