CHAPTER 4: TECHNICAL WRITING SKILLS FOR SUPPORT PROFESSIONALS A Guide to Customer Service Skills for the Service Desk Professional Third Edition

CHAPTER 4:TECHNICAL WRITING

SKILLS FOR SUPPORT PROFESSIONALS

A Guide to Customer Service Skills for the Service Desk Professional

Third Edition

Ch. 4: Tech Writing Skills2

OBJECTIVES

In this chapter you will learn:

• The impact of technology on the service desk and its customers

• The role of the service desk analyst in a technology-centric world

• The most common documents used by service desks to convey information

• The characteristics of good technical writing

• Proven techniques to improve your writing skills

143


TECHNICAL WRITING

• Dramatic changes have affected how technical support organizations

• Collect information

• Deliver support services

• All have prompted the need for technical writing skills

• Technical writing – writing documentation that explains technical issues in ways that nontechnical people can understand

144

TOPIC 1:TECHNOLOGY-DELIVERED SUPPORT

144


TECHNOLOGY-DELIVERED SUPPORT

PART 1 OF 4

• Historically, customers called or walked in to the service desk when they needed assistance or information

• Today, additional channels include

• E-mail

• Chat

• Self-service via web sites

144


Technology-delivered support services enable the service desk to:

• Anticipate and proactively meet its customers’ needs

• Reduce the overall cost of delivering support

• Prioritize and manage its workload better

• Improve service desk services


PART 2 OF 4

145


• Technology-delivered support requires service desks to:

• Diligently capture and deliver high-quality information

• Rethink the skills that service desk analysts must possess

• Rethink the skills and knowledge that customers must possess

• Used effectively, technology empowers both customers and service desk analysts

• Used improperly, technology can frustrate everyone and can alienate customers


PART 3 OF 4

145

Ch. 4: Tech Writing Skills

8

• Technologies play different roles in customer support• Telephone, IM and chat - Provide immediacy and

the ability to interact with a human being

• E-mail - Provides the ability to send and receive detailed information

• Web-based services - Provide customers with the ability to perform functions

• Analysts must • Feel comfortable communicating via all of these

methods

• Possess or develop the different skills that each of these technologies require


PART 4 OF 4

145


THE SERVICE DESK ANALYST’S ROLE IN A

TECHNOLOGY-CENTRIC WORLDPART 1 OF 2

• Analysts must continuously learn new technologies and adapt those technologies to their work

• Technologies extend the service desk’s ability to gather, organize, and use information

• Information is an extremely valuable resource

146


• People with good writing and keyboarding skills

• Quickly and easily capture needed data

• Understand the importance of complying with documentation standards

• Capture data that is accurate and consistent

• May be given a wider range of responsibilities

• Communicate efficiently and effectively with customers and management

THE SERVICE DESK ANALYST’S ROLE IN A

TECHNOLOGY-CENTRIC WORLDPART 2 OF 2

146


DIKW HIERARCHY146

Wisdom

Knowledge

Information

Data


ENABLING CUSTOMER SELF-SERVICE

• People have become accustomed to using self-services

• Self-services - Services that enable customers to help themselves

• Self-services benefit both customers and service desk analysts

• Today’s demanding customers have come to expect self-services

147


CUSTOMER SUPPORT VIA THE INTERNET

PART 1 OF 3

• The Internet has dramatically changed the way customers expect support services to be delivered

• Some companies give customers access to secured information via an extranet

• Internal service desks may enable customers to access a Web site via their company’s intranet

• Service desks offer many self-services via their Web sites

148


• Functionality and ease of use are the keys to a successful service desk Web site

•Well-designed Web sites offer customers:

• A variety of options

• The ability to obtain assistance easily when they cannot obtain the information they need

• The ability to personalize their support experience

•Web sites enable companies to cost-effectively deliver support to their customers 24 hours a day, 7 days a week


PART 2 OF 3

149



PART 3 OF 3

150


USING E-MAIL EFFECTIVELY TO

COMMUNICATE WITH CUSTOMERS PART 1 OF 4

• Many service desks use e-mail primarily for internal communication

• Some companies use e-mail to: • Inform customers about the status of

outstanding incidents and service requests

• Enable customers to submit incidents and service requests

• Automatically acknowledge that a customer’s e-mail has been received, logged, and assigned a tracking number

• Conduct customer satisfaction surveys

• Broadcast special announcements to customers

151


• E-mail does not provide the capabilities of an incident management system

• It cannot be used to automatically create trend reports or as a knowledge base

• Analysts typically log all e-mail contacts in an incident management system

• Including status updates



153


• Some companies use e-mail response management systems

• E-mail response management systems:

• Enable service desks to manage high-volume chat, e-mail, and Web form messages in much the same way that ACDs enable service desks to handle telephone calls

• Provide analysts the ability to search and review customer messages and view a history of customer activities on the support Web site



152


• Many incident management systems integrate with standard e-mail packages

• Allows automation of common tasks

• Downside of e-mail:

• Can be perceived as impersonal

• Can elongate the problem-solving process

• To minimize downsides, use common sense and courtesy



152


USING INSTANT MESSAGING AND ONLINE CHAT TO

FACILITATE COMMUNICATIONPART 1 OF 3

• Online IM and online chat are:

• Popular methods of communicating in both personal and work settings

• Cost-effective, simultaneous ways to communicate

• Instant messaging (IM) system – A system that enables two or more people to communicate in real time on the Internet

• Chat - A simultaneous text communication between two or more people via a computer

153


Service desks typically use IM to communicate internally (e.g., with level two service

providers)

• Many limit IM communications with customers

• IM does not provide many of the capabilities of an incident management system

• There can be security concerns regarding the data transmitted

• When IM is used, analysts are required to record status updates obtained in the service desk’s incident management system

• A variety of factors are causing an increase in chat use (see pp. 154-155)



154


To use IM and chat effectively, companies must:

• Establish IM guidelines that address the cost, legal, security, training, and management challenges that companies face

• Spell out the types of interactions that are appropriate for IM

• Staff this channel appropriately

• Ensure they can create a written transcript of communications between analysts and customers



154


USING AND CREATING KNOWLEDGE BASES

PART 1 OF 4

• Few companies have the resources to:

• Re-create solutions

• Give analysts adequate training

• Analysts must help themselves by learning to use and create online knowledge bases

• A knowledge base can be built using sophisticated technology or it can be a collection of books and documents

158


• Knowledge resources include:

• Class notes

• Internet sites

• Online help

• Product manuals

• An incident management system

• Co-workers and subject matter experts

• Knowledge management systems

• Provide information online when needed

• Can lead analysts through trouble-shooting steps

• Free human resources to work on unique and complex incidents


PART 2 OF 4

154


• Knowledge management systems gain flexibility and power from search retrieval technologies such as:

• Case-base reasoning (CBR)

• Decision tree

• Fuzzy logic

• Keyword searching

• Query by example (QBE)

• Search retrieval technologies have value only if the data are complete and accurate


PART 3 OF 4

160


• Many companies designate a knowledge base administrator (KBA) to • Develop and oversee the knowledge

management process

• Ensure information is accurate, complete, and current

• Ensure all information sources are added

• Provide training

• Develop documentation standards

• In smaller companies, an analyst with excellent writing skills may perform this role

• Larger companies may have one or more full-time knowledge engineers


PART 4 OF 4

161

TOPIC 2:WRITING SERVICE DESK DOCUMENTS

162


WRITING SERVICE DESK DOCUMENTS

PART 1 OF 2

• The amount of writing done by analysts varies

• Each document has a different audience and purpose

• Before writing, you must understand• The audience’s needs

• How they plan to use the information

• Applicable documentation standards

• The expected level of professionalism

• “Chat speak” may not be appropriate

• The goal of service desk writing is to accurately convey technical information in an interesting way that can be understood by readers

162


Common service desk documents include:

• Tickets

• E-mail messages

• IM and chat messages

• FAQs

• Knowledge management system solutions

• Reports

• Procedures

WRITING SERVICE DESK DOCUMENTS

PART 2 OF 2

162


TICKETSPART 1 OF 5

• Typically logged electronically at the time an incident or service request is received

• Well-written tickets provide:

• The information other analysts and service providers need to handle contacts quickly

• A historical accounting of steps taken to solve a incident

• Analyst should clearly record:

• All of the information the customer provides

• All steps taken to diagnose and resolve the incident

163


TICKETSPART 2 OF 5

163


• Tickets are typically made up of two basic parts:

• Data field - An element of a database record in which one piece of data is stored

• Text field – A field that accepts free-form information

• Text fields are used to collect detailed information

• Reports are usually created from data fields

• Many companies establish standards for how to enter certain words or phrases into text fields

• Standards help analysts write consistently and minimize confusion caused by inconsistent terms

TICKETSPART 3 OF 5

164


Accuracy is important

• Entering inaccurate date and time data can make it appear that a ticket has missed an SLA or is late

• Customers increasingly have the ability to check the status of outstanding tickets

• Trouble ticket data is often automatically forwarded to customers via e-mail

TICKETSPART 4 OF 5

164


Accuracy is important (continued)

• Ticket data is used by other service desk analysts and service providers to diagnose and solve incidents

• Ticket data is used by management to:

• Create reports and analyze trends

• Justify resources and measure performance

• Fully understand your workload and your contributions

• Identify improvement opportunities

TICKETSPART 5 OF 5

164


E-MAIL MESSAGES165

Well-written e-mail messages

• Are as clear and concise as possible

• Convey a positive, friendly tone

• Provide as much of the needed information as possible the first time

• Anticipate follow-up questions a customer may ask and volunteer the information


FREQUENTLY ASKED QUESTIONS (FAQS)16

6

Frequently Asked Questions (FAQs) – Well-written answers to the most common customer queries

• Well-written FAQs:

• State both the question and answer clearly and in a language that is appropriate to the audience

• Use jargon and technical terms in the answers as long as the terms are• Appropriate for the reader’s presumed level of skills

• Defined for the reader

• FAQs are a basic self-service

• FAQs enable customers and co-workers to find solutions and answers to questions on their own


KNOWLEDGE MANAGEMENT SYSTEM SOLUTIONS

PART 1 OF 4

167

• Must be accurate and complete or analysts will hesitate to use the system

• Resolution - A definitive solution to an incident or service request, or a proven workaround

• Typically stored as records in a separate file than tickets

• Enables a one-to-many relationship

• Solutions do not:

• Describe things to attempt when diagnosing incidents or responding to inquiries

• Checklists and tip sheets provide this capability

• Contain the details of a single specific incident or service request



PART 2 OF 4

168


• Many service desks develop standards that describe how to write resolutions

• Standard resolutions typically contain :

• Fields that are used to index the resolution and link it to the type of incident or service request being solved

• Text that describes the resolution

• The description of a solution may contain links to online documents, or a multimedia presentation such as a video or audio clip


PART 3 OF 4

167


When working in a service desk

• Strive to use all available knowledge resources

• Contribute to the creation of your company’s knowledge management system

• Respect the fact that your coworkers and other service providers are just as busy as you are; look in the knowledge base for answers to routine questions

• Seek help if you have difficulty finding solutions or using your company’s knowledge management system


PART 4 OF 4

170


REPORTSPART 1 OF 3

• Entry-level analysts may not prepare reports but senior analysts and managers often do

• Reports may be statistics or detailed accountings produced from the data collected in an incident management system

• Creating reports requires knowledge of:

• The system used to collect the data

• The available data

• The reporting package used to pull the data out of the system

171


• Reports may also reflect the results of a study, the status of a project, or the analysis of statistics

• Preparing these reports requires:

• Writing skills

• An understanding of the recipient’s expectations

• Common reports an analyst may create include:

• Progress reports

• Requirements reports

• A business case

REPORTSPART 2 OF 3

172


When asked to prepare a report for the first time:

• Find out exactly what is expected in terms of format and content

• Ask to see a copy of a similar report

• Prepare an outline and ask for feedback and approval prior to preparing actual report

• Be open to and ask for specific, constructive feedback

REPORTSPART 3 OF 3

172


PROCEDURESPART 1 OF 3

• Service desk staff are often involved in the development of policies and procedures.

• Procedures may be used by customers, the internal support organization, or within the service desk

• Procedure - A step-by-step, detailed set of instructions that describes how to perform the tasks in a process

• Many companies develop a standard format, or template, that is used to prepare procedures (see Figure 4-7)

172


Well-written procedures:

• State every step explicitly

• Use links for definitions or detailed instructions

• State the result readers can expect

• Let the reader know what to do if they do not get the expected result

• Include information about what not to do

• Include detailed warnings


172


• Many service desks create and maintain a Service Desk Analyst’s Guide

• A Service Desk Analyst’s Guide:

• Spells out the policies and procedures of the service desk

• Contains information analysts need to do their work

• Ensures the knowledge and experience of service desk management and key staff members is always available

• Is often used to orient new service desk staff members

• Should be considered a “living” document


174

TOPIC 3:IMPROVING YOUR TECHNICAL WRITING SKILLS

180


IMPROVING YOUR TECHNICAL WRITING SKILLS

• Well-written materials are:

• Simpler to comprehend

• Provide needed information

• Leave a good impression

• Writing becomes easier with practice

• Hone writing skills by paying attention when you are reading

• Excellent books and classes are available

180


TECHNICAL WRITING BEST PRACTICES

PAGE 1 OF 15

• Select an appropriate style

• Select a narrative mode

• Know your audience

• Use the active voice

• Use simple language

• Be concise

• Be specific

• Avoid or define jargon, technical terms and acronyms

• Break up your writing with lists and short sections

• Be consistent

• Check your work for accuracy and completeness

• Check your grammar, punctuation, and spelling

180


Select an appropriate style

• Many organizations develop documentation standards (style guides) that guide people creating documents

• Style guide – a set of standards for designing and writing documents

• Some organizations adopt commercially available style guides that provide generic guidance on topics such as punctuation and grammar

• The Chicago Manual of Style

• The Elements of Style


PAGE 2 OF 15

181


Select an appropriate style (continued)

• Corporate style guides offer specific guidance such as:• Document format (such as whether and how to

specify headers and footers)

• Narrative mode (such as second-person narrative)

• How terms are defined

• How figures are presented

• How documents are secured (based on their target audience)

• How the company’s brand and intellectual property rights are protected

• To avoid rework, become familiar with any applicable standards before you begin writing


PAGE 3 OF 15

181


Select a narrative mode

• Narrative mode is the point of view used to present information

• Third-person narrative is more formal and commonly used in technical writing• Pronouns include he, she, it, and they

• To avoid gender-specific pronouns (he and she), avoid pronouns altogether or use plural pronouns such as they and their


PAGE 4 OF 15

181


Select a narrative mode

• First-person narrative is typically considered inappropriate in technical writing

• Pronouns include I and we

• Second-person narrative is typically avoided in technical writing because it is directed at a single reader and can be perceived as commanding

• Pronouns include you and your

• A key to success is to select a mode and use it consistently


PAGE 5 OF 15

182


Know your Audience

• Determine the skill and education level of the intended readers

• Reader should understand your main ideas

• Define technical terms the first time you use them

• Strike a balance between a very simplistic writing style and one that is highly technical

• Tip: Know how much information your reader wants and needs


PAGE 6 OF 15

183


• Use the active voice

• The subject of a sentence causes or does the action

• Analysts update our Web site daily

• Use simple language

• Communicate more efficiently and effectively

• You can use these procedures to resolve the incident


PAGE 7 OF 15

183


• Be concise

• The fewer words you use, the better

• Attempts to resolve this recurring incident have not been successful

• Be specific

• Readers of technical writing seek detailed information, such as facts, figures, data, recommendations, and conclusions

• How good, how bad, how fast, or how slow

• We respond to e-mail messages within four hours


PAGE 8 OF 15

184


Avoid or define jargon, technical terms, and acronyms

• Use terminology that is compatible with the readers’ technical background

• Avoid technical terms when a simpler word will do just as well

• Define technical terms or acronyms the first time you use them


PAGE 9 OF 15

185


Break up your writing with lists and short sections

• Numbered sequence:

• For a blank monitor screen, check the following items:

1. Is the monitor plugged in?

2. Is the monitor powered on?

• Bulleted list:

• Consider the following when establishing a service desk:

• Your company’s goals

• Your customer’s expectations


PAGE 10 OF 15

185


Be consistent

• Inconsistencies cause confusion

• Once you have used a name or title, do not use a different name or title to refer to the same thing

• A technician will be on-site tomorrow afternoon. The technician will fix your printer and monitor.


PAGE 11 OF 15

186


Use the same grammatical construction

for each item in a list

• Inconsistent• Reasons companies establish a service desk

include:• To provide customers a single point of contact

• Minimization of support costs

• Minimize the impact of incidents and changes

• Consistent• Reasons companies establish a service desk

include:• Provide customers a single point of contact

• Minimize support costs

• Minimize the impact of incidents and changes


PAGE 12 OF 15

187


Check you work for accuracy and completeness

• Inaccurate and incomplete information wastes time and can cause incidents

• Include each step that must be followed

• Ask a coworker or subject matter expert to review complex documents for accuracy and completeness


PAGE 13 OF 15

187


Check your grammar, punctuation and spelling

• Proofread every document to eliminate errors

• Error-free documentation gain the reader’s trust and leaves a positive impression

• When in doubt about grammar, punctuation, or spelling rules

• Check a style guide or dictionary

• Ask an experienced coworker for feedback


PAGE 14 OF 15

187

Ch. 4: Tech Writing Skills 63

SIMILAR WORDS, DIFFERENT MEANINGS - 1

These words are phonetically identical, but have different meaning:

accept, except

advice, advise

affect, effect

all ready, already

all together, altogether

a lot, alot

allusion, illusion

alter, altar

among, between

our, hour

award, reward

bad, badly

beside, besides

brake, break

breathe, breath, breadth

by, bye, buy

can, may

canvas, canvass

capitol, capital

cite, site, sight

clothes, cloths

coarse, course

compare, contrast

complement, compliment

consul, council, counsel

decent, descent, dissent

delusion, illusion, allusion

desert, dessert

device, devise

faint, feint

farther, further

fewer, less

formerly, formally

forth, fourth

good, well

great, grate

hear, here

hole, whole

imply, infer

Ch. 4: Tech Writing Skills

SIMILAR WORDS, DIFFERENT MEANINGS - 2

These words are phonetically identical, but have different meaning:incidence, incidents

incite, insight

instance, instants

its, it's

knew, new

know, no

later, latter

lay, lie

lead, led

leave, let

loose, lose

notable, noticeable

object, subject

passed, past

peace, piece

plain,

plane

pore, pour

precede, proceed

precedence, precedent

presence, presents

principle, principal

quiet, quit, quite

rain, reign, rein

raise, rise

see, sea

sit, set

stationary, stationery

statue, stature, statute

then, than

their, there, they're

that, which

threw, through

to, too, two

vain, vane, vein

vociferous, voracious

waist, waste

weak, week

wearm were, where

weather, whether

whose, who's

who, whom

your, you're


I.E. OR E.G. ?

i.e.Means "that is“ Latin for “id est”Is used in place of "in other words," or "it/that is“It specifies or makes more clearExample: I'm going to the place where I work best, i.e., the coffee shop.

e.g.

Means "for example"Latin for “exempli gratia”Is used in place of "for the sake of an example“Example: At the places where I work well, e.g., Starbucks, I have none of the distractions I have at home.


Good writing skills

• Serve you well regardless of the technology you are using, the type of document you are preparing, or the audience you are trying to reach

• Enable you to promote your ideas

• Enable you to enhance your opportunities by completing a greater variety of assignments


PAGE 15 OF 15

187


E-MAIL BEST PRACTICESPART 1 OF 10

• E-mail has transitioned to a serious business tool

• Companies are under tremendous pressure to respond to e-mails quickly and professionally

• E-mail absorbs a significant amount of time during a typical work week

• An e-mail is a written document and so technical writing best practices apply

188


• Manage customer expectations

• Acknowledge the person

• Be practical and be patient

• Check your grammar, punctuation, and spelling

• Be forgiving

• Avoid lengthy discussions and debates

• Avoid negative and derogatory comments

• Use special characters, emoticons, and acronyms appropriately

• Use forms and templates to save time

• Verify your distribution lists periodically

• Standardize your signature


188


• Manage customer expectations

• The service desk must communicate its e-mail policies

• E-mail response times may be dictated by a SLA

• Acknowledge the person

• Just as you would if you were interacting in person or over the telephone

• Be considerate and respectful

• In business, it’s best to take a formal approach


189


• Use a meaningful subject line:

• A generic subject line may get mistaken for unsolicited e-mail, or spam

• "RE: Backing up your data (ticket 335262)“

• Personalize your response:

• Use the customer’s name respectfully

• Personalize your closing:

• Use a positive tone

• Make it easy for the customer to obtain assistance in the future


191


• Be practical and be patient• E-mail is not always the best way to communicate

• Use common sense

• Check your grammar, punctuation, and spelling• Form and accuracy matter

• The quality of an e-mail message constitutes a “first impression”

• Be forgiving• Simply ask for clarification or missing details

• Tactfully point out errors and offer specific suggestions


193


Avoid lengthy discussions and debates• Limit the number of subjects in a message

• Clearly distinguish a change in subjects

• List your requests at the beginning of the message

• Verify that you have answered all of the customer’s questions in the order they were presented

• Anticipate and answer any additional questions the customer may ask

• Avoid attachments unless they are essential

• Know when it is time to pickup the telephone or schedule a meeting


194


Avoid negative and derogatory comments

• What you say and how you say it is important

• Customers may misinterpret your words or interject an inappropriate emotion

• They can forward the message or print it out and hold you accountable

• If you do not want the world to see something, do not put it in an e-mail message

• Let your caring, can do attitude shine through

• Email is archived part of SEC compliance


195


• Use special characters, emoticons, and acronyms appropriately• Use special characters in the absence of formatting

features to emphasize a point

• Use emoticons sparingly and appropriately

• Use forms and templates to save time• Form – a predefined document that contains text or

graphics users cannot change and areas in which users enter data

• Template – a predefined item that can be used to quickly create a standard document or e-mail message


196


• Verify your distribution lists periodically

• Make sure you’re sending messages to the correct recipients

• Many companies provide easy ways for customers to opt out of mailing lists and specify their preferences

• Standardize your signature

• Include all the ways to contact the service desk (see Figure 4-15)

• Use the service desk’s telephone number and e-mail address


197


Guidelines for a Signature Line:

Your name & title

The company name & logo

Telephone & fax numbers

Your email address

Web site address


197


ADD A DISCLAIMER ON FORMAL EMAIL

This e-mail is for the use of the intended recipient(s) only. If you have received this e-mail in error, please notify the sender immediately and then delete it. If you are not the intended recipient, you must not use, disclose or distribute this e-mail without the author's prior permission. We have taken precautions to minimize the risk of transmitting software viruses, but we advise you to carry out your own virus checks on any attachment to this message. We cannot accept liability for any loss or damage caused by software viruses. Any views and/or opinions expressed in this e-mail are of the author only and do not represent the views of the Acme Design and Development Corporation or any other company within its group.

Consider a disclaimer when writing emails:

Privacy notification

Normally included with signature line

Limits the liability of you & your organization

Frequently not used with informal, internal email


SAMPLE SIGNATURE LINE & DISCLAIMER


WRITING FOR A GLOBAL AUDIENCE

• Technology makes it possible to interact with customers worldwide at any time of the day or night

• How you use expressions, dates, times, and numbers can confuse customers

• Avoid idioms

• Internationalize dates, times, and numbers

193

TOPIC 4:CHAPTER SUMMARY

199


CHAPTER SUMMARYPART 1 0F 3

• The Internet, e-mail, IM, and chat:

• Complement the telephone and onsite services as a way to communicate with customers

• Extend the service desk’s ability to gather, organize, and use information

• Enable companies to provide self-services that customers can use to obtain the information they need, when they need it

• Information is a valuable resource, and people with good writing skills can capture it easily and accurately

199


• In a service desk, good writing skills are needed to

• Log tickets

• Send e-mail, IM and chat message

• Develop answers to FAQs and knowledge management system solutions

• Prepare reports and procedures

• Be aware of each document’s target audience and purpose


200


• Writing improves and becomes easier with practice

• It also helps to know the rules

• Technical writing best practices

• E-mail best practices

• In today’s digital age, good writing is a critical success factor


200

CHAPTER 4 QUESTIONS

Documents

CHAPTER 4: TECHNICAL WRITING SKILLS FOR SUPPORT PROFESSIONALS A Guide to Customer Service Skills for the Service Desk Professional Third Edition