Chapter 4: Technical Writing Skills for Support Professionals

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

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

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

4. 144 Topic 1:Technology-Delivered Support

5. Technology-Delivered SupportPart 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 Ch. 4: Tech Writing Skills

6. 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 Technology-Delivered SupportPart 2 of 4 145 Ch. 4: Tech Writing Skills

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

9. The Service Desk Analyst’s Role in aTechnology-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 Ch. 4: Tech Writing Skills

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

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

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

13. Customer Support Via the InternetPart 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 Ch. 4: Tech Writing Skills

14. 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 Customer Support Via the InternetPart 2 of 3 149 Ch. 4: Tech Writing Skills

15. Customer Support Via the InternetPart 3 of 3 150 Ch. 4: Tech Writing Skills

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

17. 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 Using E-mail Effectively to Communicate with Customers Part 2 of 4 153 Ch. 4: Tech Writing Skills

18. 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 Using E-mail Effectively to Communicate with Customers Part 3 of 4 152 Ch. 4: Tech Writing Skills

19. 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 Using E-mail Effectively to Communicate with Customers Part 4 of 4 152 Ch. 4: Tech Writing Skills

20. Using Instant Messagingand 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 Ch. 4: Tech Writing Skills

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

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

23. Using and Creating Knowledge Basespart 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 Ch. 4: Tech Writing Skills

24. Using and Creating Knowledge Basespart 2 of 4 154 Ch. 4: Tech Writing Skills • 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

25. 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 Using and Creating Knowledge Basespart 3 of 4 160 Ch. 4: Tech Writing Skills

26. 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 Using and Creating Knowledge Basespart 4 of 4 161 Ch. 4: Tech Writing Skills

27. 162 Topic 2:writing service desk documents

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

29. Writing Service Desk DocumentsPart 2 of 2 162 Ch. 4: Tech Writing Skills Common service desk documents include: • Tickets • E-mail messages • IM and chat messages • FAQs • Knowledge management system solutions • Reports • Procedures

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

31. Ticketspart 2 of 5 163 Ch. 4: Tech Writing Skills

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

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

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

35. E-Mail Messages 165 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 Ch. 4: Tech Writing Skills

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

37. Knowledge Management System SolutionsPart 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

38. Knowledge Management System SolutionsPart 2 of 4 168 Ch. 4: Tech Writing Skills

39. 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 Knowledge Management System SolutionsPart 3 of 4 167 Ch. 4: Tech Writing Skills

40. 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 Knowledge Management System SolutionsPart 4 of 4 170 Ch. 4: Tech Writing Skills

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

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

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

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

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

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

47. 180 Topic 3:improving your technical writing skills

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

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

50. Technical Writing Best PracticesPage 2 of 15 181 Ch. 4: Tech Writing Skills 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