Relationships matter -- UX writing: the bridge between users and engineers

For our April meetup, Priscill Orue, Jennifer Ciroli, and Ingrid Towey talked about why relationships are key when it comes to UX writing and how to focus on the bridge between users and engineers.

Priscill is a Senior Technical Writer at Red Hat,
Jennifer is a Content Strategist at Red Hat,
and Ingrid is a Principal Technical Editor and Writing Coach at Red Hat.

Transcript

1. Relationships matter Ingrid Towey Principal Technical Editor, Writing Coach Priscill Orue Senior Technical Writer Jennifer Ciroli Content Strategist 1 UX writing: the bridge between users and engineers
2. 2 Priscill Hiking in Caminito del Rey - Malaga, Spain Ingrid (middle) Performing in Commedia dell’Arte - Italian Renaissance improv group Jennifer Based in Pittsburgh, wishing she was back on the dive boat in Belize
3. 3 What are we going to discuss? Relationships are key (Jennifer) Helping developers to understand users (Priscill) Developing relationships with teams (Jennifer) UX writing case history (Ingrid)
4. 4 What is UX writing? • User eXperience (UX) writing is the practice of designing the words that people see and hear when they interact with software. • It’s about designing the conversation between the product and the user. • It can be the microcopy on the user interface, words in error messages, and even comments in a configuration file.
5. Relationships are key Jennifer Ciroli 5 1
6. “Software engineering is a team sport” 6 Relationships are key Source: Team Geek: A Software Developer's Guide to Working Well with Others
7. Build relationships to break down silos Relationships are key 7 Image: Sick of information silos? Here’s how to break them down
8. 8 UX writer (you!) UX designers and developers Defined user flows, UI mockups, implemented UI (including text strings) User flow input, strings for the UI Your colleagues in the development adventure Relationships are key Implemented and tested product requirements, including UIs Software and quality engineers Customer requirements and feedback, branding, support, etc. Product management and other stakeholders
9. Wait … wait (for the red circle) 9 Relationships are key
10. Relationships are key 10 RTFM is not always the answer Image: MVPrint - Manuals
11. Relationships are key 11 Users are real, and they have needs. You Developers (& other stakeholders) Image: 10 steps to start doing user research OMG! A user! I’ve never seen one! They exist!!
12. Questions or comments? 12
13. Helping developers to understand users Priscill Orue 13 2
14. Understanding relationship with users 14 Image: Pixabay Users can excel in their goals when interacting with technology designed to work for them. Helping developers understand users
15. Understanding relationship with users 15 USER Helping developers understand users Usability Quality attribute that assesses user interfaces’ ease of use. User experience (UX) Person's perceptions and responses Personas Profiles representing different user types
16. • Quality attribute that assesses user interfaces’ ease of use. • Methods for improving ease-of-use during the design process. According to Nielsen Norman Group, usability is defined by five quality components: • Learnability • Efficiency • Memorability • Errors • Satisfaction 16 Helping developers understand users Usability Source: Introduction to Usability
17. In Designing for Emotion, Aarron Walter describes superior needs, such as pleasure, which can be achieved only after more foundational ones such as functionality and reliability are fulfilled. 17 User Experience Source: A Theory of User Delight: Why Usability Is the Foundation for Delightful Experiences Helping developers understand users User Experience (UX)
18. 6 months experience Entry-level skills in software design and testing; Agile Knows Java, C, C++, HTML5 and CSS Uses IntelliJ IDE Designing, developing, and modifying efficient code modules that are assigned to him by his team lead. Becoming a better programmer by absorbing information however he can: reading books, blogs and tech websites, asking questions to more senior-level colleagues, and trying new technologies that he’s discovered and been told about by his team lead. Never holding his team back from meeting a deadline or completing a deliverable. “Once I graduated from college, I thought I knew everything about programming. But I’ve since learned that it involves so much more than writing code. I needed to learn to communicate effectively with my team and be flexible when the development process breaks down. Most of all, I needed to learn how to work quickly while under pressure to deliver!” GOALS Lacking experience collaborating with a large team doing enterprise software development, as well as learning how to get the environment set up correctly, John often has questions that he has difficulty getting answers to. It’s difficult to see how his code modules fit in with the rest of the code that the team is creating - John feels like he’s looking through a keyhole to view the universe. I am under extreme pressure to deliver and spend too much time managing content and I never really know how my team or myself are doing, in terms of progress. John is eager to prove his value to his manager and the rest of the development team, so he gets to his desk at 7:00 AM, at least an hour before the next person arrives at the office. The first thing he does is re-examines the code review comments from the previous day, making sure he’s done things correctly. After that, he checks out a few tech blogs and completes a couple of modules on his online .NET training course. When he can steal some time from his team lead, he asks her a few questions about the product architecture and then asks for some technical background on the stories he’ll be likely be taking in the next sprint. John then attends the daily stand-up, and once that’s over, returns to his desk to continue working on his modules for several hours straight. The day ends with a brief check-in meeting with his manager, who wants to make sure John is able to carry out his work without problems and is adjusting well to his responsibilities. PAIN POINTS DAY IN THE LIFE... More info... John Junior Developer Application & Service implementation B.S. in Computer Science BACKGROUND
19. 6 months experience Entry-level skills in software design and testing; Agile Knows Java, C, C++, HTML5 and CSS Uses IntelliJ IDE Designing, developing, and modifying efficient code modules that are assigned to him by his team lead. Becoming a better programmer by absorbing information however he can: reading books, blogs and tech websites, asking questions to more senior-level colleagues, and trying new technologies that he’s discovered and been told about by his team lead. Never holding his team back from meeting a deadline or completing a deliverable. “Once I graduated from college, I thought I knew everything about programming. But I’ve since learned that it involves so much more than writing code. I needed to learn to communicate effectively with my team and be flexible when the development process breaks down. Most of all, I needed to learn how to work quickly while under pressure to deliver!” GOALS Lacking experience collaborating with a large team doing enterprise software development, as well as learning how to get the environment set up correctly, John often has questions that he has difficulty getting answers to. It’s difficult to see how his code modules fit in with the rest of the code that the team is creating - John feels like he’s looking through a keyhole to view the universe. I am under extreme pressure to deliver and spend too much time managing content and I never really know how my team or myself are doing, in terms of progress. John is eager to prove his value to his manager and the rest of the development team, so he gets to his desk at 7:00 AM, at least an hour before the next person arrives at the office. The first thing he does is re-examines the code review comments from the previous day, making sure he’s done things correctly. After that, he checks out a few tech blogs and completes a couple of modules on his online .NET training course. When he can steal some time from his team lead, he asks her a few questions about the product architecture and then asks for some technical background on the stories he’ll be likely be taking in the next sprint. John then attends the daily stand-up, and once that’s over, returns to his desk to continue working on his modules for several hours straight. The day ends with a brief check-in meeting with his manager, who wants to make sure John is able to carry out his work without problems and is adjusting well to his responsibilities. PAIN POINTS DAY IN THE LIFE... More info... John Junior Developer Application & Service implementation B.S. in Computer Science BACKGROUND “Once I graduated from college, I thought I knew everything about programming. But I’ve since learned that it involves so much more than writing code. I needed to learn to communicate effectively with my team and be flexible when the development process breaks down. Most of all, I needed to learn how to work quickly while under pressure to deliver!”
20. 20 Use cases based on UX Writing Helping developers understand users USER Error messages Empty states UX Writing aspects • Facilitate relationship between engineers with users, where Technical Writers act as word experts in their role of UX Writers. Empty states UX Writing aspects
21. Use cases to build relationship with users 21 Empty states Key guidelines: Moments in a user’s experience with a product where there is nothing to display. Example: not knowing where to start after software was recently installed. • Identify the goal of the empty state: ◦ Initial interactions ◦ Accomplishments • Inform the user • Provide next steps • Be playful (when applicable) Sources: Writing empty states from the UX Collective and Empty States – The Most Overlooked Aspect of UX from Shane Ketterman Helping developers understand users
22. Use cases to build relationship with users 22 Empty states Helping developers understand users
23. Use cases to build relationship with users 23 Error messages Key guidelines: Unexpected behavior of the application, due to user’s wrong input, incorrect navigation flow, or network issues. • Inform the user • Provide next steps • Be precise • Use human-readable language: very important if you are working with CLIs (Command Line Interfaces) and APIs (Application Programming Interfaces) Helping developers understand users Sources: Error Message Guidelines from Nielsen Norman Group.
24. Use cases to build relationship with users 24 Error message Helping developers understand users
25. Use cases to build relationship with users 25 Other UX Writing aspects … Key guidelines: Localization: UI strings can contain a description of the context where they are used. Accessibility: Depending on the programming languages used in the front end, the same UI strings can be used as ARIA labels because “developers should prefer using the correct semantic HTML element over using ARIA” (Mozilla 2020). • Know your users • Learn the technology stack used for your product Helping developers understand users
26. Questions or comments? 26
27. Developing relationships with teams Jennifer Ciroli 27 3
28. Start with a shared goal 28 Image: Bear Market blog Developing relationships with teams
29. Understand & manage the team’s expectations 29 - Image: Why do expectations hurt and how can we deal with them. • Knows that a UX writer can fix links and UI text on an existing application (expects cooperative approach) • Knows that a UX writer can share ownership of UI content with engineers (expects collaborative approach) • Doesn’t know what a UX writer does (no expectations) Developing relationships with teams
30. Working together: The cooperative approach 30 We need your help with a few things … Developing relationships with teams
31. Working together: The collaborative approach 31 Developing relationships with teams Image: Team Collaboration - Illustration
32. Example: Collaborative approach 32 Developing relationships with teams Agreed-upon process between Red Hat 3scale UXD, UX writers, and UI developers
33. Show commitment and build trust 33 Show up and speak up Know the product Be present and prepared to ask intelligent questions or make informed suggestions. Deliver high-quality work on time. Be reliable, transparent, and adaptable. Developing relationships with teams Don’t forget about user and business goals, and related industry trends. Do what you promised
34. Don’t forget to bring your curiosity … 34 Image: How to achieve a successful working relationship with public contributors Developing relationships with teams
35. Questions or comments? 35
36. UX writing case history: Relationships in action* Ingrid Towey 36 4 *Based on a true story
37. 37 It all started with an email . . . UX Writing case history
38. Hi Ingrid, This is XXXXXX, a developer from subscription engineering, GSS. I am working on the NTP configuration app. It is designed to help customers configure NTP servers and clients. The link to the app in CI is https:// . Could you spare some time to help me with the wording in the app as well as the info page? Attachment is the draft of info page of the app. As the production gear has not been created yet, I put it in a text file. Thanks a lot. Regards, XXXXXX 38 The email had a request and something to edit Info page for NTP configuration app The NTP configuration app is an attempt to help you set up servers running the NTP service or clients synchronized with NTP servers. You will go through a server or client configuration guide according to your selection on the app's initial page. There are several profiles that will define different configuration. The only information you need to provide is the servers of a higher stratum for the server/client being configured. If the servers are cryptographic, you have to input the symmetric key as well. You have options to enable historical log with ntpd behavior and symmetric key cryptography. The application will offer you with configuration script for a specific profile. UX Writing case history
39. 39 Original help text Info page for NTP configuration app The NTP configuration app is an attempt to help you set up servers running the NTP service or clients synchronized with NTP servers. You will go through a server or client configuration guide according to your selection on the app's initial page. There are several profiles that will define different configuration. The only information you need to provide is the servers of a higher stratum for the server/client being configured. If the servers are cryptographic, you have to input the symmetric key as well. You have options to enable historical log with ntpd behavior and symmetric key cryptography. The application will offer you with configuration script for a specific profile. Readability Scores • Flesch-Kincaid grade level: 10.5 (US high school) • Flesch Reading Ease: 45.9 (out of 100) UX Writing case history
40. 40 Rewritten help file for NTP configuration UX Writing case history
41. 41 The floodgates began to open . . . UX Writing case history Image: Pixabay - Victoria Falls
42. 42 We reworked the navigation menus for the iSCSI Helper app Before After All the options are now action oriented and begin with verbs. UX Writing case history
43. 43 We changed microcopy in Rescue Mode Assistant Before After Before you begin You must be able to boot the system into rescue mode with one of the following installation media: • A boot CD-ROM or DVD • Other installation boot media, such as USB flash devices • The Red Hat® Enterprise Linux® installation DVD If you do NOT have any installation media, download it from: https://access.redhat.com/downloads UX Writing case history
44. 44 We worked more and more together . . . UX Writing case history Image: Flood dancing couple, by Krypto.
45. 45 Before: Ceph PGs Per Pool Calculator UX Writing case history
46. 46 After: Ceph PGs Per Pool Calculator UX Writing case history
47. 47 Cooperation →Collaboration UX Writing case history Image: Pixabay
48. Key takeaways • Software engineering is a team sport, and you’re a valuable asset. Time spent building relationships is never wasted. • Basic use cases such as empty states and error messages help developers understand users. • You may have to start small and simple in your UX writing. But if you let the relationship build naturally, you can have a big impact. 48
49. More questions? 49
50. linkedin.com/company/red-hat youtube.com/user/RedHatVideos facebook.com/redhatinc twitter.com/RedHat Red Hat is the world’s leading provider of enterprise open source software solutions. Award-winning support, training, and consulting services make Red Hat a trusted adviser to the Fortune 500. Thank you 50
51. References • Team Geek: A Software Developer's Guide to Working Well with Others • Sick of information silos? Here’s how to break them down • MVPrint manuals • 10 steps to start doing user research • A Theory of User Delight: Why Usability Is the Foundation for Delightful Experiences • Writing empty states • Empty States – The Most Overlooked Aspect of UX • Error Message Guidelines • Why do expectations hurt and how can we deal with them. • How to achieve a successful working relationship with public contributors 51