 So welcome to this talk giving your user interfaces a voice and Yep, let us quickly introduce ourselves. My name is Andreas. I am a UX designer on the cockpit web console Hi, I'm Shweta. I'm a part of the real documentation team And hi, I am Vendula and I'm also part of the real documentation team so today we're gonna talk about How we've been working together as UX designers and technical writers, but first I want to talk about the subject of the day Microcopy so micro copy is are the tiny bits of text in a product It's the labels of the buttons the error messages the field labels Simple but it's it's pretty much everything you can read in a UI And why is this important? So here's why I think it's important to keep your Microcopy or interface text tip top It's the way you communicate through UI you and the way you have a conversation with the user of the interface and you use this language to guide and through the application and responding to your inquiries in fact a large portion of your graphical UI are just text even more so with a CLI interface and consistency Within the application But more importantly with other touch points that the person who uses the interface are really important such in our case the reddit customer portal reddit satellite reddit insights and Having this language It minimizes confusion, but most importantly instills trust in user that this is something they can trust and they can use And then clear and simple text Is is just more accessible Making sure that you use simple English makes your interface more accessible to people who might not have English as their first language But still they might be using your interface in English such as myself today So and even though they'll have English as their first language Might have not have a higher reading comprehension generally or it could be such a nice Situational it could be that they don't have a high reading comprehension because they're in a hurry They don't have time to to go through it in detail. So it needs to be simple and straightforward So here is an example here is the application We're going to talk about today the cockpit web console and as you can see we have quite a lot of micro copy So Thank you Andreas for sharing the case studies and for the insights on why micro copy is important Yes, I can't agree more that micro copy is one of the important aspects of user interfaces and also the command line interfaces We're glad that we got an opportunity to work with you and to contribute to positive user experience It's really exciting to see how teams can work together to bring in that positive experience for the user Now we have seen that typically a project has team members from project management who work with the customers and bring in the Requirement for the products. There are US designers who work on the layout which the users later on get to use There are UI Designers who are at the artistic elements to this layout They are developed. There are developers and QEs who work on the core features of the product But there are also a group of people who are called technical writers who typically join in late in the project But they work for documenting the end user documents and documenting the features of the product for the users to use it now these technical writers also work with the cross-functional teams and Can help assist to document or to write the UI text to write the error messages to write the tooltips and the CLI messages Collectively they can partner with the teams to work on the micro copy Now, let's see how can you involve your writing buddies on the projects that you work Now because writers are the first users They bring in the user's perspective and they can be your audience for usability testing Now we also discussed how you how writers can help to craft the UI text or error messages or tooltips or CLI messages But the main question is how can you involve your writing buddies? The traditionally we have seen writers are the last group of people who join the project Typically during the documentation phase, but this really does not help them Because it takes a great deal of effort to understand a requirement or a feature after the product has been developed At times it so happens that the talent who is available for the knowledge transfer has already moved on to another project And then there's a limitation with the knowledge transfer And in such a scenario it gets difficult for the writer to step up and to bring in some valuable suggestions It might also happen that even though the valuable suggestion is valid But it gets difficult to implement that change because the development cycle is already complete So ideally the best time to involve your writing buddies Is to call them during the planning meetings, during the functionality discussions and also during the UI mock-up sessions if there are any Now how will you actually partner with them? You can send in your mock-ups for review, you can tag them in the FATTIB Zira ticket It's also a good idea to share your test setups with them And just we need to go to the next slide please So it's also a good idea to share the test setups with them You can also try and get their hands on so that they can try their hands on the functionalities that are under development While the while they review the mock-ups, they also suggest the UI test Possibly they can also suggest some functionality improvements Now Will the writer's suggestion be perfect in the first go? Well, definitely not. There are so many if-and-if not clauses which they might not be aware of There are so many technical aspects that they might not be aware of so your suggestions, your valuable inputs are going to help them To come up with better text and in turn it's going to improve the user experience So if you haven't started to collaborate with your writers, I would encourage this is the time that you start Your collaboration with them. With that I'll now hand it over back to Andrea's to talk about some work that we have done together Thank you for that. So yes, we've spoken a little bit about the theory But now we're going to talk about it how we work together in practice as you give designers and technical writers so the first thing I want to show is The UI for network bonding so a problem was network bonding is hard So for those who are not familiar with the concept of network bonding It's a way to bring together several network interfaces To handle for example the network load better or to act as a backup in case of hardware failure We wanted to create something that was simple and straightforward for our UI and here is version one so This was good, but we always make sure that for all the UIs we developed we also tried to run a usability test so We put a user in front of the UI and give them a task and See how well the UI performs in that case in this case. We were on a study with 10 people Participants all of them cis admins But they have mostly had experience with managing Windows Server and not specifically Linux or Linux networking Usually kind of thing that you get out of this kind of study is that do you realize that you use the wrong kind of Interface element or something is in an unexpected place or it's something that an error state has a wording that is Confusing or incorrect But in this case what make as a big problem was that the networking concept themselves was Was very hard The names for them was things like balance round robin 802 ad etc And the actual concept of how they worked Was something that was hard to comprehend for for these Participants So after a lot of food back and forth With the between the development team and documentation team We where we tried to to to do our best to to help this in the interface as much as possible We realized that we actually had to go ahead and put this Explanations of these different networking modes into the documentation But not only we did we do this, but we also made sure that we had handy pointers To the places in the documentation where people could find out more Easily accessible from the UI itself. So we implemented this help menu, but not only that we also inside of the networking dialogue here we Implemented some inline help In this case about network bonding where it's on a high level explains the concept and then gives you a handy pointer Where you can read more and understand the different Yeah, behaviors of these different network modes And now I'm with the worker bundler and she'll talk about her side of this experience Yeah, thank you Andreas, but I joined the cockpit team Andreas asked me for help. I need to add text here and there and it is too long Help me to make it shorter and let's add more clarity there So I tried but actually Andrea's his texts were almost perfect So I was not able to help much at all or at all But you know, I often hear from teams. We don't need documentation because we have a great user experience designer NTS user experience designer is a very important role in the product development But it is not a silver bullet that resolves everything the fact that the technical writer The technical writer complements nice nicely great UX design and well-designed application so documentation according I Think that documentation should be natural part of the product So with the great graphical user interface You don't definitely don't need documentation for basic workflows But if the topic becomes complex, you need to start to learn about it We need to deliver the learning material for you and the designer ensures That documentation is accessible and visible at the right place you cannot Understand bond modes from graphical user interface, right? This is a complex networking topic that must be properly explained and The explanation must be placed where you need it And that's what we've done actually we edit documentation directly to the product and edit direct Learn more link to the bond settings dialog box So now I'm going to show you another Example where we also collaborated but in a slightly different web fashion. So this is what I called it is this age leap of faith so This is a login screen for for the copy's web console that you can see on any rel or fedora or Yeah, what is it Susie would do whatever system And you it allows you to log in to to that particular host that particular server But you there is also functionality where you can use this first system as a fashion host that allows you to Talk to a machine that maybe you are not you cannot access directly But that a machine that you have access to can access through a firewall or similar But there comes a challenge that once you try to log in for the first time You need to trust that you're actually connecting to the correct post Because we use this through SSH. So our first version of this was Something that is very very similar to just the SSH command-line Tooling where you say they say, okay, the authentication cannot be established And here's a fingerprint. Whatever that means so we Realized that we actually had to provide more context in this place What's a favorite? How do you verify it? What does it mean? That's like why why are you throwing me this this? Except in the first place, why are you asking me to take a leap of faith? What is what is the things that I could run into? So we work together with Shweta And then we came up with something like this where we give you the information that you need in this Particular case just there and there and then so you can easily know what you're doing Even if this is the first time you're you're seeing this interface So now I'm gonna hand it over to Shweta and she's gonna talk about it from her perspective Thank you, Andrea for sharing this success story It was indeed an exciting piece of work Especially because of the collaboration that we had and I cannot forget the number of back-and-forth discussions we had I remember I had jumped in quite late in the cycle and the functionality Discussions had already taken place by then it was a bit challenging to catch up with the functionality of this screen And then the multiple use cases that we were trying to address on one single screen to save one time I did come up with my questions and my understanding about this screen and this Corrections and the suggestions and inputs that I had received helped me to phrase the text in the first place Now the original screen mentioned eavesdropping a man in the middle is attacking you and then a redundant checkbox to accept the key and to log in Now when I first took a look at the mock-up these words sounded very alarming to me Well, a third-party attempting to intercept the connection was one of the alert message that we wanted to give but The commonly use the common use case that we wanted to bring out here was due to the operating system reinstallation There's a change in the key The first version of my suggestion was pretty much close by to it But later on came in the various use cases that we wanted to consider and then it got challenging But it was all fun at the end and it was exciting to see how everyone was jumping in to try their hands on and How we ended up in shaping up the text. I would say it was a learning experience for all of us And we ended up in a result that was satisfactory. I hope it will be very useful for the users, too Now with that I handed over to Vendila and she would like to share her thoughts and advantages of including or involving your right to buddies Thank You Shweta Technical writer is one of the customer advocates in your team Once you start to write documentation and you see that it is too complex and hard to write There are a lot of if else clauses It is an indicator that the feature may not be designed well Your writer can warn you in the development phase or if you share your mock-ups with them Even before the development phase starts that something doesn't go so well Writing UX text is a standalone discipline today you need to understand rules and apply them on your on all your texts and It doesn't matter if we are speaking about graphic user or command-line interfaces Writers also regularly see a bigger picture and ensure consistency of used terms Because they may be in touch with marketing support delivery development quality engineering product manager and of course user experience designer, too Therefore sometimes writers have a unique perspective That can give additional value to your product and made your users a little bit happier or at least less Frustrated in in certain point or certain situation while using your your application Next slide please and there else and this is I guess the the last one If we still have some time I have a following I have some resources for you about microcopy the first one is a pattern flight style guide So there are all these rules That you need for creating good UI texts Second link takes you to the 10 usability heuristics for each of these heuristics There is a short three-minute video tutorial that gives you a great introduction to this topic Third one is a book if you like books from Kinect Ifra, so try try to Buy one and if you liked today's presentations or introductions look at the recording of our yesterday Defcon talk later when there is a recording Top things we need to learn about UX where we talked about UX writing and user experience Design and showed some other examples from Fedora's cockpit web console