Chapter 4: Technical Writing Skills for Support Professionals

Chapter 4: Technical Writing Skills for Support Professionals
A Guide to Customer Service Skills for the Service Desk Professional Third Edition

Objectives In this chapter you will learn:
143 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 Ch. 4: Tech Writing Skills

Technical Writing 144 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 Ch. 4: Tech Writing Skills

Topic 1: Technology-Delivered Support
144 Topic 1: Technology-Delivered Support

Technology-Delivered Support Part 1 of 4
144 Historically, customers called or walked in to the service desk when they needed assistance or information Today, additional channels include Chat Self-service via web sites Ch. 4: Tech Writing Skills

145 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 Ch. 4: Tech Writing Skills

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 Ch. 4: Tech Writing Skills

145 Technologies play different roles in customer support Telephone, IM and chat - Provide immediacy and the ability to interact with a human being - 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 Ch. 4: Tech Writing Skills

The Service Desk Analyst’s Role in a Technology-Centric World part 1 of 2
146 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 Ch. 4: Tech Writing Skills

The Service Desk Analyst’s Role in a Technology-Centric World part 2 of 2
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 Ch. 4: Tech Writing Skills

DIKW Hierarchy Wisdom Knowledge Information Data 146
Ch. 4: Tech Writing Skills

Enabling Customer Self-Service
147 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 Ch. 4: Tech Writing Skills

Customer Support Via the Internet Part 1 of 3
148 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 Ch. 4: Tech Writing Skills

149 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 Ch. 4: Tech Writing Skills

150 Ch. 4: Tech Writing Skills

Using E-mail Effectively to Communicate with Customers Part 1 of 4
151 Many service desks use primarily for internal communication Some companies use 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 Ch. 4: Tech Writing Skills

153 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 contacts in an incident management system Including status updates Ch. 4: Tech Writing Skills

152 Some companies use response management systems 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 Ch. 4: Tech Writing Skills

152 Many incident management systems integrate with standard packages Allows automation of common tasks Downside of Can be perceived as impersonal Can elongate the problem-solving process To minimize downsides, use common sense and courtesy Ch. 4: Tech Writing Skills

Using Instant Messaging and Online Chat to Facilitate Communication part 1 of 3
153 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 Ch. 4: Tech Writing Skills

Using Instant Messaging and Online Chat to Facilitate Communication part 2 of 3
154 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 ) Ch. 4: Tech Writing Skills

To use IM and chat effectively, companies must:
Using Instant Messaging and Online Chat to Facilitate Communication part 3 of 3 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 Ch. 4: Tech Writing Skills

Using and Creating Knowledge Bases part 1 of 4
158 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 Ch. 4: Tech Writing Skills

154 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 Ch. 4: Tech Writing Skills

160 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 Ch. 4: Tech Writing Skills

161 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 Ch. 4: Tech Writing Skills

Topic 2: writing service desk documents
162 Topic 2: writing service desk documents

Writing Service Desk Documents Part 1 of 2
162 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 Ch. 4: Tech Writing Skills

Common service desk documents include:
Writing Service Desk Documents Part 2 of 2 162 Common service desk documents include: Tickets messages IM and chat messages FAQs Knowledge management system solutions Reports Procedures Ch. 4: Tech Writing Skills

Tickets part 1 of 5 163 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 Ch. 4: Tech Writing Skills

Tickets part 2 of 5 163 Ch. 4: Tech Writing Skills

Tickets part 3 of 5 Tickets are typically made up of two basic parts:
164 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 Ch. 4: Tech Writing Skills

Tickets part 4 of 5 Accuracy is important
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 Ch. 4: Tech Writing Skills

Accuracy is important (continued)
Tickets part 5 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 Ch. 4: Tech Writing Skills

Well-written e-mail messages
165 Well-written 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 Ch. 4: Tech Writing Skills

Frequently Asked Questions (FAQs)
166 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 Ch. 4: Tech Writing Skills

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 Ch. 4: Tech Writing Skills

168 Ch. 4: Tech Writing Skills

167 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 Ch. 4: Tech Writing Skills

When working in a service desk
Knowledge Management System Solutions Part 4 of 4 170 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 Ch. 4: Tech Writing Skills

Reports Part 1 of 3 171 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 Ch. 4: Tech Writing Skills

Reports Part 2 of 3 172 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 Ch. 4: Tech Writing Skills

When asked to prepare a report for the first time:
Reports Part 3 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 Ch. 4: Tech Writing Skills

Procedures Part 1 of 3 172 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) Ch. 4: Tech Writing Skills

Well-written procedures:
Procedures Part 2 of 3 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 Ch. 4: Tech Writing Skills

Procedures Part 3 of 3 174 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 Ch. 4: Tech Writing Skills

Topic 3: improving your technical writing skills
180 Topic 3: improving your technical writing skills

Improving Your Technical Writing Skills
180 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 Ch. 4: Tech Writing Skills

Technical Writing Best Practices Page 1 of 15
180 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 Ch. 4: Tech Writing Skills

Select an appropriate style
Technical Writing Best Practices Page 2 of 15 181 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 Ch. 4: Tech Writing Skills

Select an appropriate style (continued)
Technical Writing Best Practices Page 3 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 Ch. 4: Tech Writing Skills

Select a narrative mode
Technical Writing Best Practices Page 4 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 Ch. 4: Tech Writing Skills

Select a narrative mode
Technical Writing Best Practices Page 5 of 15 182 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 Ch. 4: Tech Writing Skills

183 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 Ch. 4: Tech Writing Skills

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 Ch. 4: Tech Writing Skills

184 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 messages within four hours Ch. 4: Tech Writing Skills

Avoid or define jargon, technical terms, and acronyms
Technical Writing Best Practices Page 9 of 15 185 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 Ch. 4: Tech Writing Skills

Break up your writing with lists and short sections
Technical Writing Best Practices Page 10 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 Ch. 4: Tech Writing Skills

186 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. Ch. 4: Tech Writing Skills

Use the same grammatical construction
Technical Writing Best Practices Page 12 of 15 187 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 Provide customers a single point of contact Minimize support costs Ch. 4: Tech Writing Skills

Check you work for accuracy and completeness
Technical Writing Best Practices Page 13 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 Ch. 4: Tech Writing Skills

Check your grammar, punctuation and spelling
Technical Writing Best Practices Page 14 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 Ch. 4: Tech Writing Skills

Similar Words, Different Meanings - 1
These words are phonetically identical, but have different meaning: Ch. 4: Tech Writing Skills

Similar Words, Different Meanings - 2
These words are phonetically identical, but have different meaning: Ch. 4: Tech Writing Skills

i.e. Or e.g. ? i.e. e.g. Means "that is“ Latin for “id est”
Is used in place of "in other words," or "it/that is“ It specifies or makes more clear Example: 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. Ch. 4: Tech Writing Skills

187 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 Ch. 4: Tech Writing Skills

E-Mail Best Practices Part 1 of 10
188 has transitioned to a serious business tool Companies are under tremendous pressure to respond to s quickly and professionally absorbs a significant amount of time during a typical work week An is a written document and so technical writing best practices apply Ch. 4: Tech Writing Skills

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 Ch. 4: Tech Writing Skills

189 Manage customer expectations The service desk must communicate its policies 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 Ch. 4: Tech Writing Skills

191 Use a meaningful subject line: A generic subject line may get mistaken for unsolicited , or spam "RE: Backing up your data (ticket )“ 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 Ch. 4: Tech Writing Skills

193 Be practical and be patient 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 message constitutes a “first impression” Be forgiving Simply ask for clarification or missing details Tactfully point out errors and offer specific suggestions Ch. 4: Tech Writing Skills

Avoid lengthy discussions and debates
Best Practices Part 6 of 10 194 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 Ch. 4: Tech Writing Skills

Avoid negative and derogatory comments
Best Practices Part 7 of 10 195 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 message Let your caring, can do attitude shine through is archived part of SEC compliance Ch. 4: Tech Writing Skills

196 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 message Ch. 4: Tech Writing Skills

197 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 address Ch. 4: Tech Writing Skills

197 Guidelines for a Signature Line: Your name & title The company name & logo Telephone & fax numbers Your address Web site address Ch. 4: Tech Writing Skills

Add a Disclaimer on formal email
Consider a disclaimer when writing s: Privacy notification Normally included with signature line Limits the liability of you & your organization Frequently not used with informal, internal This is for the use of the intended recipient(s) only. If you have received this 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 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 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. Ch. 4: Tech Writing Skills

Sample Signature Line & Disclaimer
Ch. 4: Tech Writing Skills

Writing for a Global Audience
193 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 Ch. 4: Tech Writing Skills

Topic 4: Chapter summary
199 Topic 4: Chapter summary

Chapter Summary part 1 0f 3 The Internet, e-mail, IM, and chat:
199 The Internet, , 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 Ch. 4: Tech Writing Skills

Chapter Summary part 2 0f 3 200 In a service desk, good writing skills are needed to Log tickets Send , 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 Ch. 4: Tech Writing Skills

Chapter Summary part 3 0f 3 200 Writing improves and becomes easier with practice It also helps to know the rules Technical writing best practices best practices In today’s digital age, good writing is a critical success factor Ch. 4: Tech Writing Skills

Chapter 4 Questions

Chapter 4: Technical Writing Skills for Support Professionals

Similar presentations

Presentation on theme: "Chapter 4: Technical Writing Skills for Support Professionals"— Presentation transcript:

Similar presentations

About project

Feedback

Log in

Auth with social network:

Chapter 4: Technical Writing Skills for Support Professionals

Similar presentations

Presentation on theme: "Chapter 4: Technical Writing Skills for Support Professionals"— Presentation transcript:

Similar presentations

About project

Feedback