From an error message project to our content design system
How we scaled UX writing best practices by creating a “content kit” within OLX Brazil’s design system.
By Maria Santos, Douglas Ferreira and Flávia Gonçalves
Have you found problems standardizing and scaling consistent error messages in a digital product? We faced this issue at OLX Brazil. We will tell you how we ended up with our content design system.
To run this project, we count on the collaboration of many of our colleagues, product designers, and product managers.
We three represent our multidisciplinary design team: Maria is our UX writer, Douglas is a senior product designer, specializing in design ops and our design system champion, and Flávia is our product design intern, focused on our design system.
Inconsistency in error messages
When we say error messages here, we mean the UI copy in these messages and the UI components themselves.
We already had design system documentation and a content style guide, including a special section for error messages. Still, we found a legacy with many different ways to deliver these messages to our users, even for the same type of errors, for example, connection or server.
This legacy also made it harder for new product designers with new projects to understand which of the existing messages was the “correct” option to apply in the interfaces they were working on.
As a result of this mess, we could find dozens of “standards”:
Therefore, we decided to combine the design system and UX writing specialties, so they worked in this standardization.
Prioritizing messages and flows
With our long legacy and our team of over 40 designers divided into different verticals, tribes, and squads, working on multiple devices and platforms, we were sure we couldn’t cover all the existing and new error messages.
So, we developed the following criteria to choose messages and/or flows to start:
- The impact of the message in relevant metrics on the user experience.
- Messages or flows cross verticals and teams.
- Flows with many distinct types of error messages.
- The teams’ capability to implement our new version as soon as possible.
Categorizing the error messages
The flows with various error messages (e.g., identity or telephone validation) especially helped us to understand the standards we already had. From them, we could start to categorize the most common cases, so we defined these three macro categories:
*️⃣Inline error: when the users fill a field with invalid information, or it is a required field, but they try to submit without filling it.
🚧Detour error: when something is preventing the users from following the flow, but they can choose alternatives or fix it.
⛔Blocking error: when something happens, e.g., business rules or system problems that make it impossible for users to follow the flow.
Related to these categories, we found different types of errors in the flows and messages we had prioritized:
Working on useful and engaging documentation
Once we organized these categories and types of errors, we noticed the documentation would take a long time to read, even more considering the existing recommendations, such as the structure of the error messages, dos & don’ts, and the application of the company’s voice and style, etc.
Also, we already had evidence of product designers’ difficulties consulting our documentation before each prototype.
Aiming to increase their engagement with our documentation, we prepared some tools to help them to define the UI copy and component for the error messages:
1)Standard error message table
In this table, they can identify the type of message in the column “what is wrong”, read a direct recommendation about “what we should do in each case”, and then an example of our UI copy and visual standards.
2)Decision flowchart for error messages
We added the decision flowchart to our documentation to make it more interactive and easier to share this more straightforward decision-making method in other channels.
Including a “content kit” within the design system
Even with this new material and more engaging documentation, we could imagine the product designer’s routine and challenges in applying our definitions and standards to the error messages. So, we developed one more tool to help them:
3) Content kit
We have created a facility for our designers and collaborators where they can simply enable the design system library and have access to the content kit library.
To make it possible, we applied the atomic design concept to separate the visual component from the UI copy. Here is one example of how we used it in an alert box:
- We componentized the copy (title, description, and button link), according to the need and UX writing principles.
- We named using the “/” in each component to create a folder within the page on Figma.
- We created the component on the same page within subpages organizing it according to our categories: inline, detour, and blocking.
- We called it our “content kit”, and added this componentized UI copy to the component itself (alert box) in our design system.
- We used the “sections”, a new Figma functionality, to keep everything more organized.
- We copied this basic content kit scheme following the categories from the alert box to apply to other components.
The main benefit of creating them separately, but making them accessible just from one library, is the freedom to expand, improve and manage them without affecting each other.
Customizing the UI copy
Another important point for us was allowing a certain level of customization in our content kit. Standardization + customization could sound conflicting, but it makes sense when we talk about copy.
We promote consistency in our tones and voice, style, and UI in general, but not necessarily in the word choices, when, most of the time, we try to customize according to the moment of the user in their journey. So, in our first scenarios, we always have a customizable option for the component.
In addition, in some cases, we bring a recommendation between [ ] to fill that space considering the specific business model. Sometimes, we link it to our content style guide, where they can find more detailed instructions to define that UI copy.
Ok, we have seen these UI memes of digital products running with this kind of [ ] to fill, but we trust our team❤️ enough to believe it can’t happen to our product, but just in case, these tools and workshops help them to define the UI copy with confidence and consistency in a scaled way.
Designing the evolution of this content design system
The idea of the project is always to foster the application of the UX writing/content design best practices.
We identified our standards, documented how to apply UX writing, improved documentation, unified to design system, and disseminated this information. Now, we count on continuous work to improve this content design system “systematically”:
- Measuring the impact on user experience: we are documenting hypotheses for each adoption of our defined standards to have clear feedback on the scenarios that work best, could be improved, or fixed.
From the results of our first implementation, we had an 25% reduction in support tickets related to an error message users couldn’t easily understand.
- Adding new message samples: from the results and the analyses of new flows and cases, we can map and add messages to our tables, flowchart, and design system through the content kit.
- Creating new components: we can find out if we have the necessity of a new component, and with our partnership with the design system team, it could be easier to prioritize the development of a new component.
- Preventing errors: we are working on improving the content design to prevent errors from occurring, and adjusting specific business rules, value propositions, and/or the product itself, considering that sometimes we can’t fix everything on the UI.
- Using checklists: we are adding a checklist to help them check our voice, tones, style, and UX writing principles.
As a result of this project, we expect a more clear, concise, useful, and consistent UX copy, independent of the team or person who defines UI copy, impacting our metrics positively, mainly on the user experience.
Give us feedback and let us know how you handle error messages, content style guides, and/or design systems.
Some references for this article:
- UX Writers Need Design System, Too! presentation in Config 2022 - Pinda Phisitbutra.
Would you like to join us at OLX Brazil and be a part of this multidisciplinary and collaborative team? Check out our vacancies.
