PowerPoint Presentation and Survey
Chapter 3
Writing for End Users
A Guide to Computer User Support for Help Desk and Support Specialists Sixth Edition by Fred Beisse
1
Chapter Objectives
Types of end-user documentation
How technical writing differs from other writing
How technical documents are organized
How to plan effective user documents
The technical writing process
Effective use of formats
Strategies for technical writing
Common problems in technical writing
Tools used for technical writing
How to evaluate documents
2
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
2
Technical Writing
Documentation: written communication to provide information to end users or coworkers
Goal of technical writing: to produce documents that effectively and efficiently communicate information that readers need
Effectively: Readers get correct information to master a topic or perform a task
Efficiently: Readers do not have to waste time searching for information
Good technical writing saves users time
3
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Types of User Documents
Brochures and flyers
Newsletters
Handouts and training aids
User guides and manuals
Online help systems
4
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Email, chat, and text messages
Webpages
Proposals, letters, and memos
Procedural and operational documents
Troubleshooting guides
Brochures and Flyers
Purpose: primarily promotional
Catch the eye of the reader and sell an event
Use to advertise:
Staff training sessions
Computer fairs
Career fairs
Product demonstrations
Guest speakers
5
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Newsletters
Purpose: communicate information
From support group to end users
Popular in large companies where support staff does not regularly contact other workers
Formats:
Printed
Electronic distribution
6
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Handouts and Training Aids
Purpose: summarize and promote recall of material covered in training session
Common example: printouts of PowerPoint slides
Usually short and address a single topic
May be distributed online
7
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
User Guides, Handbooks, and Manuals
Purpose: supplement vendor documents and trade books with information specific to an organization or computer facility
Structure:
Tutorial format: a step-by-step guide to hardware or software features (in learning sequence)
Reference format: all material on each topic is covered in a single location (more comprehensive)
Combination format: tutorial plus reference
8
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Online Help Systems
Purpose:
Provide convenient access to information
Replace or supplement printed materials
Features:
Information presented must be succinct
Hyperlinks, indexes, and keyword searches provide powerful tools to locate information quickly
Tip: Not all users are adept at using online materials; some still prefer the printed format
9
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Email, Chat, and Text Messages
Purpose: formal and informal online communication
With external clients and vendors
With internal end users and coworkers
Caveats:
Messages project an image of the organization and support specialist
Use good technical writing skills
Avoid the use of abbreviations (U, BTW, IMHO, etc.)
Tip: Growth in the use of written communications emphasizes the need for user support specialists with excellent writing skills
10
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Webpages
Purpose: provide access to support materials on the web
Need to be organized and written so users can locate information quickly and easily
Must be short, but contain hypertext links to additional information
Image of organization is projected in web documents
An ongoing challenge is to keep web-based support information current and accurate
11
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Proposals, Letters, and Memos
Purpose: technology tools are often used to prepare correspondence
Proposals
Letters
Memos
Needs assessment reports
Performance appraisals
Other correspondence
Ability to prepare basic business correspondence is an important user support skill
12
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Procedural and Operational Documents
Purpose: procedure steps and checklists are primarily for internal use
Examples:
Written problem reports in a help desk environment
Descriptions of hardware or software installation procedures
Entries in Site Management Notebook (see Chapter 10)
13
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Troubleshooting Guides
Purpose: help support agents and computer users diagnose and solve problems
Examples:
Troubleshooting section in user manual
FAQ on problems users encounter frequently
Script on incident handling procedures
Problem report in help desk knowledge base
Must be clear, concise, and well written
14
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
How Technical Writing Differs from Other Writing
Differences in:
Goals
Organization of document
Type of information communicated
Writing style
15
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Technical Writing Characteristics
Economical writing style
Begins with the most important information first
Communicates information vital to the readers productivity
Uses styles and formats that help readers understand a sequence of events and document organization
Is concise, but not cryptic
Includes pointers and cross-references
Focuses on information, not entertainment
16
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Technical Writing Characteristics (continued)
Strategies:
Use short, simple, declarative sentences, phrases, and lists
Describe a sequence of steps in the order performed
Include pointers to where readers can find more information
Use format elements to help readers understand:
Organization of information
Transitions between topics
Avoid:
Run-on sentences
Humor
Calling attention to the writers personality or style
17
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
How Technical Documents Are Organized
Sequential organization: follows a step-by-step sequence from first to last
Example: procedural check list for installation of hardware or software
Hierarchical organization: flows from top to bottom, and from general to specific information
Example: an online help system
18
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Common Organization for Technical Documents
Introduction
Purpose of document
Intended audience
Why read document
Body
Specific task steps
Common problems users encounter
Summary
Review of main points
Pointers to additional information
19
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Document Planning
Who is the target audience?
What does the audience already know?
What does the audience need to know?
What do you want the audience to be able to do when they finish reading the document?
What medium will be used to transmit the document to its audience?
20
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Help the Reader
Target the reading level at 10th to 12th grade
Most word processors include a readability index
Tell readers who the intended audience is
Organize the document so experienced readers can skip basic materials
State the documents purpose in the first few sentences
Tell readers which tasks they can perform after completing the document
Tailor the document to the media
Printed: generally longer; help readers with topic transitions
Online: generally shorter; help readers with pointers to additional information
21
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Steps in the Technical Writing Process
Generate a list of ideas or features
Organize the list into a logical sequence (outline)
Expand the outline into a first draft
Edit the draft for clarity
Arrange for an outside review
Revise the draft into its final form
Proofread the final document
22
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Step 1: Generate an Idea List
Brainstorm: a technique to generate a list of potential topics
During brainstorming, exclude nothing
Dont worry about whether a topic is:
Major or minor
Useful or not
High or low priority
23
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
23
Step 2: Organize the List into an Outline
Arrange topics into a logical sequence
Identify major and minor topics
Cut and paste to try a different sequence of ideas
Use the word processors outline feature as a tool
Final organization should answer the following question:
In what order does a reader need to know this information?
24
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Step 3: Expand the Outline into a First Draft
Strategies
Each paragraph has a topic sentence
Use transitions between paragraphs and sections
First . . ., Second . . ., Next . . ., Then . . ., Finally . . .
Define terms
In text
In glossary
Format features
Style elements
Format consistency
Lists and tables
25
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Step 3: Expand the Outline into a First Draft (continued)
Style elements help reveal document structure:
Chapter or modular organization
Fonts
Capitalization
Centering
Indentation
Underlines
Bullets and numbered lists
Format consistency helps ensure consistent use of style elements
Use style sheets and templates in a word processor
Lists and tables help readers locate information quickly
Use instead of long narrative passages
26
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Step 4: Edit the Draft
Pass 1: Eliminate extra words
Pass 2: Perform a format consistency check
Consistent use of fonts for headings and subheadings, indentation, centering, boldface, italics, and underlining
Tip: Overuse of format features detracts from the document contents
Pass 3: Perform a technical accuracy check
Test procedural or technical steps
Eliminate errors in instructions
Check URLs for dead links
Verify screenshots
27
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Step 5: Get an Outside Review
Purpose:
Identify and clarify any questions about contents
Spot inconsistencies
Find unclear meanings
Identify poor writing techniques
Locate other problems
Tip: Sometimes a writer is too close to a document to see problems
28
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Step 6: Revise the Draft
Incorporate revisions into a document
Tip: When an edit pass results in marginal improvements, consider the document done
29
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Step 7: Proofread the Document
Final pass through the document before publication
Look for:
Typos
Inconsistent capitalization and punctuation
Inconsistent font use
Extra spaces between words and sentences
Incorrect page breaks
30
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Technical Writing Strategies
Analogy: describes how an unfamiliar concept is similar to a familiar concept
Repetition
Introduce
Explain
Summarize
Consistent word use
Use a consistent word to refer to each concept
Avoid varying: DVD, DVD-ROM, digital video 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 events clearly occurred in the past
31
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Sample Page from a Style Sheet
32
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Technical Writing Strategies (continued)
33
Parallel structure: similar items are treated consistently throughout a list or document
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Common Technical Writing Problems
Clutter
Inappropriate typefaces
Gender references
Unclear referents
Passive voice
34
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Nominalization
Wordiness
Jargon
Undefined acronyms and intialisms
Idioms
Dangling phrases
Clutter
Use graphics to illustrate (screenshot) or highlight a point
Not for decoration
Use formatting to help locate information or understand a topic
Use sparingly and consistently
Include considerable white space
Use at least 10-point body text
Larger for slide shows, brochures, flyers
Left-align most body text
Centered text and block-justified text are harder to read
35
Justified text is aligned at both the right and left margins, like this
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Inappropriate Typefaces
Serif typefaces: include fine lines (serifs) that project from the top and bottom of characters
Frequently used for body text
Sans serif typefaces: do not have serifs
Often used for titles and headings
Specialty typefaces: type styles intended for special use to draw attention to text
Save for informal use
Invitations, brochures, flyers
36
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Example Typefaces
Which is most readable?
This is an example of a 28-point serif typeface called Georgia.
This is an example of a 28-point sans serif typeface called Arial.
This is an example of a 37-point script typeface called Brush Script.
37
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
37
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 other examples?
38
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Unclear Referents
Referent: a concrete word or concept that is designated (referred to) by another word
The referent of words such as it, them, this, he, she and their should be clear
Example: A user in Excel on an HP Pavilion PC entered a long list of numbers with a voice recognition utility program. Halfway through the list, it froze up.
Does it refer to the HP Pavilion PC, Excel, the voice recognition utility, or the user?
39
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Passive Voice
Passive voice: the subject of the sentence receives the action indicated by the verb
Example: The final report was filed.
Avoid passive voice
Active voice: the subject of the sentence performs the action indicated by the verb
Example: The project team filed its final report.
Use active voice to make text livelier and more interesting
40
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Nominalization
Nominalization: the use of -tion, -ing, -ment, and similar 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.
41
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
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 or utilization
Use document instead of documentation
Use added instead of additional
Can you think of other examples?
42
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Jargon
Jargon: words understood primarily by those experienced in a field
Use simple, direct words that anyone can understand
Example:
Avoid: Hack the documentation for the new VPN connection steps.
Use: Edit the document for the new network connection steps.
Tip: If you use jargon terms, define them first
43
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Undefined Acronyms and Initialisms
Acronym: a word formed from the initial letters of words in a phrase
Example: RAM is an acronym for random access memory
An acronym is pronounced as a word (i.e., ram)
Initialism: an abbreviation formed from the initial letters of words in a phrase
Example: USB an initialism for universal serial bus
An initialism is pronounced as a sequence of letters (i.e, u-s-b)
44
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Handling Acronyms and Initialisms
On the first use of an acronym or initialism:
Spell out the words
Then include the acronym or initialism in parentheses
Example: digital video disc (DVD)
Tip: Include acronyms and initialisms in a glossary
Tip: Dont create unnecessary new acronyms or initialisms
Example: Writers Against Unnecessary Words and Acronym Use (WAUWAU)
45
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Idioms
Idiom: a word or phrase whose meaning is different from the literal meaning of the separate words
Example: Keep an eye out for users who have their antivirus application turned off.
Better: Be aware of users who have their antivirus application turned off.
46
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Dangling Modifier
Dangling modifier: a word or phrase at the beginning or end of a sentence that adds little meaning
Example: Needless to say, the installer should verify that the users PC is operational, of course.
Eliminate the word (or phrase), or include it elsewhere in the sentence
Better: The installer should verify that the users PC is operational.
47
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Technical Writing Tools
Outline tool
Spell checker
Custom dictionary
Thesaurus
Grammar checker
Readability index
Desktop publishing features
Collegiate dictionary
48
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Document Evaluation Criteria (Overview)
Content
Organization
Format
Mechanics
49
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Content
Is the information relevant?
Is the information timely and accurate?
Is the coverage of the topic complete?
50
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Organization
Is the information easy to locate?
Are transitions between topics identifiable?
Can readers get in and out quickly with the answer they need?
51
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Format
Does the layout help guide the reader?
Is the format consistent?
52
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Mechanics
Are words spelled correctly?
Is it grammatically correct?
Is the writing style effective?
53
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Chapter Summary
User support staff write a variety of 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:
Defines characteristics of the target audience and tasks the writer wants readers to be able to do
Uses short words and sentences, and an organization that helps readers locate information
54
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Chapter Summary (continued)
The technical writing process includes these steps:
Generate a list of ideas or features
Organize the list into a logical sequence (outline)
Expand the outline into a first draft
Edit the draft for clarity
Arrange for an outside review
Revise the draft into its final form
Proofread the final document
The documents layout and formatting help readers know what is important and identify transitions between topics
Technical writers use analogies, repetition, consistent words, and parallel structure
55
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Chapter Summary (continued)
Successful writers avoid clutter, hard-to-read typefaces, gender references, unclear referents, passive voice, nominalizations, wordiness, jargon, acronyms and initialisms, idioms, and dangling modifiers
Software tools that aid writers include an outline tool, spell checker, thesaurus, and grammar checker
Four criteria to evaluate technical documents:
Content
Organization
Format
Mechanics
56
A Guide to Computer User Support for Help Desk and Support Specialists, Sixth Edition
Applied Sciences
Architecture and Design
Biology
Business & Finance
Chemistry
Computer Science
Geography
Geology
Education
Engineering
English
Environmental science
Spanish
Government
History
Human Resource Management
Information Systems
Law
Literature
Mathematics
Nursing
Physics
Political Science
Psychology
Reading
Science
Social Science
Liberty University
New Hampshire University
Strayer University
University Of Phoenix
Walden University
Home
Homework Answers
Blog
Archive
Tags
Reviews
Contact
twitterfacebook
Copyright © 2022 SweetStudy.com
Recent Comments