Message Improvement How Writers are Making a Difference

Message Improvement: How Writers are Making a Difference in Product Quality and Customer Satisfaction Kyla Cragg Martin Schwirzke Publications Manager Senior Technical Writer kylac@cadence. com schwirzk@cadence. com 1 CADENCE DESIGN SYSTEMS, INC.

The Dark Side of Software 2

Does This Sound Familiar? “Make error messages less cryptic. ” "What exactly does this warning mean, and should we be concerned? Please be advised this is holding up our tapeout. So it’s rather urgent we resolve this issue ASAP. “ “If you could do one thing that would save me hours each week it would be to improve error messages. ” “Please provide a clue as to what has happened. ” “Error messages are as useless as teats on a boar. ” 3

Why Do I Care? Improving error messages is strategic to success on the job! • Higher profile of technical communicators in the company • Lower costs (Support, R&D) • Increased productivity (internal and external) • Increased customer satisfaction Technical communicators are in the best position to write or edit error messages because it requires writing skills and understanding the user's needs—both of which are prime skills of technical communicators 4

Your file was so big. It might be very useful. But now it is gone. 5

How We Started on the Road to Improvement • Beginning with three – Support, Usability and Technical Publications • Expanding the team • Developing a roadmap – Prioritizing helps immensely • Creating and testing the guidelines – We consulted R&D and customers extensively • Getting acceptance – Research is needed to gain buy-in 6

Acceptance There is only one way to ensure acceptance and buy-in: Data • Error message related calls range from 14 -25% of all Support calls, varying by software product • Error message related calls take, on average, 25% longer than other calls to resolve 7

Where We Are Now • Published message writing guidelines • Achieved support from our worldwide VP of R&D • Included in the company’s annual technical conference • Developed a message system requirements specification • Partnered with an R&D team chartered with creating a standard message system 8

Three things are certain. Death, taxes, and lost data. Guess which has occurred. 9

Case Studies The following case studies demonstrate the various approaches we’ve taken over the past 18 months to address error message improvement and include the following details: • How they started • What process was followed • What the preliminary results were 10

Case Study 1: Camouflage • Selected by our VP of Worldwide Support • Process • Preliminary Results – 5% of the cases were rewritten – 25% of the cases were related to another product area, 10% were bugs, and the remaining 60% were miscellaneous issues Example: ”Error: Calling function exceeds nestability limit of 5. “ “Error: VRTU-321 The calling function exceeds the nestability limit of 5, deactivating the Schematic window edit commands. To activate the edit commands, set the nestability default to hi. Get. CIWindow() nest. Limit=20 in the Command Interpreter Window. ” 11

Case Study 2: Special Operations • Writer initiative and EMI project direction • Moved to one message system • Preliminary Results: – Reviewed and rewrote approximately 635 messages, taking an average of 20 minutes per message Example: “ERROR ‘(pi. Read. Cdba) - db. Create. Lib failed (%s)n’, ctg. Lib. Name” “ERROR: PIPO-521 Failed to create the temporary library `%s'. Check that you have write permission to the run directory and 'cds. lib' file. ” “Stream Out is unable to create a temporary library. This library is required when you use the `Convert Pcells to Geometry‘ option. ” 12

Case Study 3: Stealth Bombers • Writer initiative • Process • Reviewed 224 messages for one functional area – 211 messages were revised or rewritten – Total writer time was 44. 5 hours • Review messages as needed by developers – Review and rewrite time no different than that of a paragraph in a manual – Developers ask for reviews/rewrites 13

Case Study 4: Mission Possible • Writer initiative • Process • Preliminary results – Process is continuing to be used on new projects due to writer experience/credibility with the R&D teams – Spends about 2 weeks per release on messages 14

Case Study 5: The Mess Tent • Coincidental Pubs and Support initiatives • Too many messages to count across product areas • Preliminary results – 40 of the biggest offenders were documented for one functional area in the manual and published on the company’s external web site – 281 messages were reviewed and about 30% completely rewritten in the messages file itself for another functional area – Customers are asking for more – First writer hired devoted strictly to error message improvement 15

Lessons Learned Whether you’re in a small company or a large one, you have to start somewhere and you have to start small. • Pick a pilot project • Prove your method works • Expand as you go • Publicize success stories • Never give up 16

Summary (E)ffort (R)elationships (buy-in, expertise) (R)ecognize need to be flexible (compromise—lots of it) (O)ften publicize (promote to increase corporate awareness) (R)eady, set, go! (start now) 17

References and Resources • Schwirzk@cadence. com • Kylac@cadence. com • Chatelaine, Julianne. “Polite, Personable Error Messages. ” Usability Interface, January 1998, Volume 4, Number 3. • Fisher, Julie (1999). “The Importance of User Message Text and Why Professional Writers Should be Involved. ” 18

Windows NT crashed. I am the Blue Screen of Death. No one hears you scream. 19