About the Presentations
Chapter 3Writing for End UsersA Guide toComputer User Supportfor
Help Desk and Support Specialists Sixth Edition by Fred
Beisse1Chapter ObjectivesTypes of end-user documentationHow
technical writing differs from other writingHow technical documents
are organizedHow to plan effective user documentsThe technical
writing processEffective use of formats Strategies for technical
writingCommon problems in technical writingTools used for technical
writingHow to evaluate documents2A Guide to Computer User Support
for Help Desk and Support Specialists, Sixth Edition2Technical
WritingDocumentation: written communication to provide information
to end users or coworkersGoal of technical writing: to produce
documents that effectively and efficiently communicate information
that readers needEffectively: Readers get correct information to
master a topic or perform a taskEfficiently: Readers do not have to
waste time searching for informationGood technical writing saves
users time3A Guide to Computer User Support for Help Desk and
Support Specialists, Sixth EditionIts all about the person you are
writing to and for!Types of User DocumentsBrochures and
flyersNewslettersHandouts and training aidsUser guides and
manualsOnline help systems4A Guide to Computer User Support for
Help Desk and Support Specialists, Sixth EditionEmail, chat, and
text messagesWebpagesProposals, letters, and memosProcedural and
operational documentsTroubleshooting guidesBrochures and
FlyersPurpose: primarily promotionalCatch the eye of the reader and
sell an eventUse to advertise:Staff training sessionsComputer
fairsCareer fairsProduct demonstrationsGuest speakers5A Guide to
Computer User Support for Help Desk and Support Specialists, Sixth
EditionNewslettersPurpose: communicate informationFrom support
group to end usersPopular in large companies where support staff
does not regularly contact other workersFormats:PrintedElectronic
distribution6A Guide to Computer User Support for Help Desk and
Support Specialists, Sixth EditionHandouts and Training
AidsPurpose: summarize and promote recall of material covered in
training sessionCommon example: printouts of PowerPoint slides
Usually short and address a single topicMay be distributed online7A
Guide to Computer User Support for Help Desk and Support
Specialists, Sixth EditionUser Guides, Handbooks, and
ManualsPurpose: supplement vendor documents and trade books with
information specific to an organization or computer
facilityStructure: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 referenceCreative
approach: Cartoon, parable, simulation8A Guide to Computer User
Support for Help Desk and Support Specialists, Sixth
EditionCartoon/Simulation
9A Guide to Computer User Support for Help Desk and Support
Specialists, Sixth EditionOnline Help SystemsPurpose:Provide
convenient access to informationReplace or supplement printed
materialsFeatures:Information presented must be succinctHyperlinks,
indexes, and keyword searches provide powerful tools to locate
information quicklyTip: Not all users are adept at using online
materials; some still prefer the printed formatTip: Not all users
are adept at using printed materials; some are put off by or lose
papers10A Guide to Computer User Support for Help Desk and Support
Specialists, Sixth EditionEmail, Chat, and Text MessagesPurpose:
formal and informal online communicationWith external clients and
vendorsWith internal end users and coworkers Caveats:Messages
project an image of the organization and support specialistUse good
technical writing skillsAvoid 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 skills11A Guide to Computer User Support for Help Desk and
Support Specialists, Sixth EditionWebpagesPurpose: provide access
to support materials on the webNeed to be organized and written so
users can locate information quickly and easilyMust be short, but
contain hypertext links to additional informationImage of
organization is projected in web documentsAn ongoing challenge is
to keep web-based support information current and accurate12A Guide
to Computer User Support for Help Desk and Support Specialists,
Sixth EditionProposals, Letters, and MemosPurpose: technology tools
are often used to prepare correspondence ProposalsLettersMemosNeeds
assessment reportsPerformance appraisalsOther correspondenceAbility
to prepare basic business correspondence is an important user
support skill13A Guide to Computer User Support for Help Desk and
Support Specialists, Sixth EditionProposal:First page has why we
need it, how much it costs, how much it is worth.Further pages have
tech detailsProcedural and Operational DocumentsPurpose: procedure
steps and checklists are primarily for internal useExamples:Written
problem reports in a help desk environmentDescriptions of hardware
or software installation proceduresEntries in Site Management
Notebook (see Chapter 10)14A Guide to Computer User Support for
Help Desk and Support Specialists, Sixth EditionCan (and should)
you put a checklist into the form of a document used to prove
something was done correctly?Troubleshooting GuidesPurpose: help
support agents and computer users diagnose and solve
problemsExamples:Troubleshooting section in user manual FAQ on
problems users encounter frequentlyScript on incident handling
proceduresProblem report in help desk knowledge baseMust be clear,
concise, and well written15A Guide to Computer User Support for
Help Desk and Support Specialists, Sixth EditionHow Technical
Writing Differsfrom Other WritingDifferences in:GoalsOrganization
of documentType of information communicatedWriting style16A Guide
to Computer User Support for Help Desk and Support Specialists,
Sixth EditionTechnical Writing CharacteristicsEconomical writing
styleCorrect balance of why and howCarefully-chosen exampleBegins
with the most important information firstCommunicates information
vital to the readers productivityUses styles and formats that help
readers understand a sequence of events and document organizationIs
concise, but not crypticIncludes pointers and
cross-referencesFocuses on information, not entertainment17A Guide
to Computer User Support for Help Desk and Support Specialists,
Sixth EditionTechnical Writing Characteristics
(continued)Strategies:Use short, simple, declarative sentences,
phrases, and listsDescribe a sequence of steps in the order
performedInclude pointers to where readers can find more
informationUse format elements to help readers understand:
Organization of informationTransitions between topicsAvoid:Run-on
sentencesHumorCalling attention to the writers personality or
style18A Guide to Computer User Support for Help Desk and Support
Specialists, Sixth EditionHow Technical Documents Are
OrganizedSequential organization: follows a step-by-step sequence
from first to lastExample: procedural check list for installation
of hardware or softwareHierarchical organization: flows from top to
bottom, and from general to specific informationExample: an online
help system19A Guide to Computer User Support for Help Desk and
Support Specialists, Sixth EditionCommon Organization for Technical
DocumentsIntroductionPurpose of documentIntended audienceWhy read
documentBodySpecific task stepsCommon problems users
encounterSummaryReview of main pointsPointers to additional
information 20A Guide to Computer User Support for Help Desk and
Support Specialists, Sixth EditionDocument PlanningWho is the
target audience?What does the audience already know?If they dont,
where can they find it?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?21A Guide to Computer User Support for Help Desk and
Support Specialists, Sixth EditionHelp the ReaderTarget the reading
level at 10th to 12th gradeMost word processors include a
readability indexTell readers who the intended audience isOrganize
the document so experienced readers can skip basic materialsState
the documents purpose in the first few sentencesTell readers which
tasks they can perform after completing the documentTailor the
document to the mediaPrinted: generally longer; help readers with
topic transitionsOnline: generally shorter; help readers with
pointers to additional information22A Guide to Computer User
Support for Help Desk and Support Specialists, Sixth
EditionPop-outs and read more links Steps in the Technical Writing
ProcessGenerate a list of ideas or featuresOrganize the list into a
logical sequence (outline)Expand the outline into a first draftEdit
the draft for clarityArrange for an outside reviewRevise the draft
into its final formProofread the final document23A Guide to
Computer User Support for Help Desk and Support Specialists, Sixth
EditionStep 1: Generate an Idea ListBrainstorm: a technique to
generate a list of potential topicsDuring brainstorming, exclude
nothingDont worry about whether a topic is:Major or minorUseful or
notHigh or low priority24A Guide to Computer User Support for Help
Desk and Support Specialists, Sixth Edition24Step 2: Organize the
Listinto an OutlineArrange topics into a logical sequenceIdentify
major and minor topicsCut and paste to try a different sequence of
ideasUse the word processors outline feature as a toolFinal
organization should answer the following question:In what order
does a reader need to know this information?25A Guide to Computer
User Support for Help Desk and Support Specialists, Sixth
EditionStep 3: Expand the Outlineinto a First DraftStrategiesEach
paragraph has a topic sentenceUse transitions between paragraphs
and sectionsFirst . . ., Second . . ., Next . . ., Then . . .,
Finally . . .Define termsIn textIn glossaryFormat featuresStyle
elementsFormat consistencyLists and tables26A Guide to Computer
User Support for Help Desk and Support Specialists, Sixth
EditionStep 3: Expand the Outlineinto a First Draft
(continued)Style elements help reveal document structure:Chapter or
modular
organizationFontsCapitalizationCenteringIndentationUnderlinesBullets
and numbered listsFormat consistency helps ensure consistent use of
style elements Use style sheets and templates in a word
processorLists and tables help readers locate information
quicklyUse instead of long narrative passages 27A Guide to Computer
User Support for Help Desk and Support Specialists, Sixth
EditionStep 4: Edit the DraftPass 1: Eliminate extra wordsPass 2:
Perform a format consistency checkConsistent use of fonts for
headings and subheadings, indentation, centering, boldface,
italics, and underliningTip: Overuse of format features detracts
from the document contentsPass 3: Perform a technical accuracy
checkTest procedural or technical stepsEliminate errors in
instructionsCheck URLs for dead linksVerify screenshots28A Guide to
Computer User Support for Help Desk and Support Specialists, Sixth
EditionIf you show an example, what are the precursor conditions
for this example to work?Step 5: Get an Outside
ReviewPurpose:Identify and clarify any questions about contentsSpot
inconsistencies Find unclear meaningsIdentify poor writing
techniquesLocate other problemsTip: Sometimes a writer is too close
to a document to see problems 29A Guide to Computer User Support
for Help Desk and Support Specialists, Sixth EditionStep 6: Revise
the DraftIncorporate revisions into a documentTip: When an edit
pass results in marginal improvements, consider the document
done30A Guide to Computer User Support for Help Desk and Support
Specialists, Sixth EditionStep 7: Proofread the DocumentFinal pass
through the document before publicationLook for:TyposInconsistent
capitalization and punctuationInconsistent font useExtra spaces
between words and sentencesIncorrect page breaks31A Guide to
Computer User Support for Help Desk and Support Specialists, Sixth
EditionTechnical Writing StrategiesAnalogy: describes how an
unfamiliar concept is similar to a familiar
conceptRepetitionIntroduce ExplainSummarizeConsistent word useUse a
consistent word to refer to each conceptAvoid varying: DVD,
DVD-ROM, digital video disc, optical diskStyle sheet: lists
preferences for spelling and word useExample: end user is a noun;
end-user is an adjectiveConsistent verb tensePrefer present tense
unless events clearly occurred in the past32A Guide to Computer
User Support for Help Desk and Support Specialists, Sixth
EditionSample Page from a Style Sheet33A Guide to Computer User
Support for Help Desk and Support Specialists, Sixth Edition
Technical Writing Strategies (continued)34 Parallel structure:
similar items are treated consistently throughout a list or
documentA Guide to Computer User Support for Help Desk and Support
Specialists, Sixth Edition
Common Technical Writing ProblemsClutterInappropriate
typefacesGender referencesUnclear referentsPassive voice35A Guide
to Computer User Support for Help Desk and Support Specialists,
Sixth EditionNominalizationWordinessJargonUndefined acronyms and
intialismsIdiomsDangling phrasesClutterUse graphics to illustrate
(screenshot) or highlight a pointNot for decorationUse formatting
to help locate information or understand a topicUse sparingly and
consistentlyInclude considerable white spaceUse at least 10-point
body textLarger for slide shows, brochures, flyersLeft-align most
body textCentered text and block-justified text are harder to
read36Justified text is aligned at both the right and left margins,
like thisA Guide to Computer User Support for Help Desk and Support
Specialists, Sixth EditionInappropriate TypefacesSerif typefaces:
include fine lines (serifs) that project from the top and bottom of
charactersFrequently used for body textSans serif typefaces: do not
have serifsOften used for titles and headingsSpecialty typefaces:
type styles intended for special use to draw attention to textSave
for informal useInvitations, brochures, flyers37A Guide to Computer
User Support for Help Desk and Support Specialists, Sixth
EditionExample TypefacesWhich 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.38A Guide to Computer User Support for Help Desk and Support
Specialists, Sixth Edition38Gender ReferencesAvoid gender-related
words unless they clearly fitAvoid: he, she, him, her, s/heUse:
they, their, it, he and she, she and heGender-neutral words are
clearer and less offensiveUse staffed instead of mannedUse chair
instead of chairmanUse supervisor instead of foremanCan you think
of other examples?39A Guide to Computer User Support for Help Desk
and Support Specialists, Sixth EditionUnclear ReferentsReferent: a
concrete word or concept that is designated (referred to) by
another wordThe referent of words such as it, them, this, he, she
and their should be clearExample: 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?40A Guide to Computer User Support for Help Desk and Support
Specialists, Sixth EditionPassive VoicePassive voice: the subject
of the sentence receives the action indicated by the verbExample:
The final report was filed.Avoid passive voiceActive voice: the
subject of the sentence performs the action indicated by the
verbExample: The project team filed its final report.Use active
voice to make text livelier and more interesting41A Guide to
Computer User Support for Help Desk and Support Specialists, Sixth
EditionNominalizationNominalization: the use of -tion, -ing, -ment,
and similar endings to create nouns where verbs are easier to
understandExample:Use of nominalization: Perform an installation of
the printer driver.Use of verb: Install the printer driver.42A
Guide to Computer User Support for Help Desk and Support
Specialists, Sixth EditionWordinessAvoid unnecessary wordsToo many
words: Prior to the actual installation of the system...Reduced:
Before installing the system...Use short words when possibleUse use
instead of utilize or utilizationUse document instead of
documentationUse added instead of additionalCan you think of other
examples?43A Guide to Computer User Support for Help Desk and
Support Specialists, Sixth EditionJargonJargon: words understood
primarily by those experienced in a fieldUse simple, direct words
that anyone can understandExample: 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
first44A Guide to Computer User Support for Help Desk and Support
Specialists, Sixth EditionUndefined Acronyms and
InitialismsAcronym: a word formed from the initial letters of words
in a phrase Example: RAM is an acronym for random access memoryAn
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 busAn initialism is
pronounced as a sequence of letters (i.e, u-s-b)45A Guide to
Computer User Support for Help Desk and Support Specialists, Sixth
EditionHandling Acronyms and InitialismsOn the first use of an
acronym or initialism:Spell out the wordsThen include the acronym
or initialism in parenthesesExample: digital video disc (DVD)Tip:
Include acronyms and initialisms in a glossaryTip: Dont create
unnecessary new acronyms or initialismsExample: Writers Against
Unnecessary Words and Acronym Use (WAUWAU) 46A Guide to Computer
User Support for Help Desk and Support Specialists, Sixth
EditionIdiomsIdiom: a word or phrase whose meaning is different
from the literal meaning of the separate wordsExample: 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.47A Guide to Computer User Support for Help Desk and
Support Specialists, Sixth EditionDangling ModifierDangling
modifier: a word or phrase at the beginning or end of a sentence
that adds little meaningExample: 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
sentenceBetter: The installer should verify that the users PC is
operational.
48A Guide to Computer User Support for Help Desk and Support
Specialists, Sixth EditionTechnical Writing ToolsOutline toolSpell
checkerCustom dictionaryThesaurusGrammar checkerReadability
indexDesktop publishing featuresCollegiate dictionary49A Guide to
Computer User Support for Help Desk and Support Specialists, Sixth
EditionDocument Evaluation Criteria
(Overview)ContentOrganizationFormatMechanics50A Guide to Computer
User Support for Help Desk and Support Specialists, Sixth
EditionContentIs the information relevant?Is the information timely
and accurate?Is the coverage of the topic complete?51A Guide to
Computer User Support for Help Desk and Support Specialists, Sixth
EditionOrganizationIs the information easy to locate?Are
transitions between topics identifiable?Can readers get in and out
quickly with the answer they need?52A Guide to Computer User
Support for Help Desk and Support Specialists, Sixth
EditionFormatDoes the layout help guide the reader?Is the format
consistent?53A Guide to Computer User Support for Help Desk and
Support Specialists, Sixth EditionMechanicsAre words spelled
correctly?Is it grammatically correct?Is the writing style
effective?54A Guide to Computer User Support for Help Desk and
Support Specialists, Sixth EditionChapter SummaryUser support staff
write a variety of types of documents to communicate with end
users, coworkers, vendors, and managersThe goal of technical
documents is to effectively and efficiently communicate information
needed by the readerTechnical writing:Defines characteristics of
the target audience and tasks the writer wants readers to be able
to doUses short words and sentences, and an organization that helps
readers locate information55A Guide to Computer User Support for
Help Desk and Support Specialists, Sixth EditionChapter Summary
(continued)The technical writing process includes these
steps:Generate a list of ideas or featuresOrganize the list into a
logical sequence (outline)Expand the outline into a first draftEdit
the draft for clarityArrange for an outside reviewRevise the draft
into its final formProofread the final documentThe documents layout
and formatting help readers know what is important and identify
transitions between topicsTechnical writers use analogies,
repetition, consistent words, and parallel structure56A Guide to
Computer User Support for Help Desk and Support Specialists, Sixth
EditionChapter 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 modifiersSoftware tools that aid
writers include an outline tool, spell checker, thesaurus, and
grammar checkerFour criteria to evaluate technical
documents:ContentOrganizationFormatMechanics57A Guide to Computer
User Support for Help Desk and Support Specialists, Sixth
Edition
