UX Writing for a Design System: What I Learned
From a UX Writer’s perspective, the pains and joys of documenting a Design System.
This story is a continuation of the conversation about Design Systems that I started here.
How I helped build the Design System with the RD Station Design team and what an exciting learning experience it has been!
Organization
Here at RD Station, I work on the Design Ops team, and one of our big projects is the development of a Design System… and things can get pretty busy.
A critical point for me has always been to keep the requests organized. Luckily, we work well aligned with daily meetings and a very up-to-date Kanban, making it very easy to keep track of components in the backlog, those that are being designed, and those that are already under development on the front-end.
Keeping this routine is super important for a few reasons: you can study the components at the moment they are being created, and you can signal early on if you have any impediment from the writing part.
Another really cool point of working with the components from the beginning is that, as the UX Writer has a broader view of the product, it is possible to give opinions and bring valuable ideas to designers, who are often focused on just one use case of that component. You have a lot of chances to know more use cases than anyone else on the team.
Finally, I like to review and give help in writing the component documentation. It makes me understand even more about the application of each component.
Tools
Here we work with Figma, Storybook, and Zero Height.
Before joining the team, I had never had contact with either of these tools, but I could count on the team to quickly learn some things that help me daily.
It is not necessary to understand them in detail, but this lets you contribute more actively to Design System construction.
Figma
In Figma, I created a branch of the writing style guide focused on components. In this component writing guide, I have mapped the main components and defined how texts should be constructed for them and use cases for what to do and what not to do.
Figma makes it much easier for people to learn best practices since they are in it all day long and don’t need to access another tool or document.
Storybook
Engineering uses Storybook to consume components. Therefore, the documentation in it needs to be 100% correct.
The Storybook needs to be updated when any changes are made to the component. Updates are performed on Github. As a result, I also learned how to submit PRs (pull requests), which is basically how I let front-end developers know about something that needs to be updated.
Zero Height
We use Zero Height to present the Design System to the entire company. It has a friendly interface, and the Figma integration makes it all easy.
Arranging everything on this platform helped us ensure that what people are using to create the screens are the latest versions of the components. In Figma, if the administration is not very well done, sometimes people end up using components that have expired.
You will often have to redo
When it comes to updating, it is pretty normal for some component’s definitions to be revised, and sometimes this will spill over into your work.
But don’t be frustrated! For me, this is one of the beauties of participating closely in the construction of a DS documentation. A few years ago, it was unthinkable to have someone looking at the text of this type of product, so it is a step forward to see a DS born already with the participation of a UX Writer.
Changes can often come from you. Fresh eyes make a difference, and, at the end of the day, a DS documentation has to be understood by everyone. It can’t be a developer-only product. Your role in this is important. Making documentation accessible is very important for the company as a whole.
Highlights
- Beyond components:
As I said earlier, I created the text definitions for components, but that went further. Within the Design System, we also have the guidelines for Localization and Accessibility, for example, which was an opportunity to learn a lot. - Use cases:
The more use cases you can present, the better for the Design System. Describe each component in detail, but make sure to provide a visual example of how it relates to your product. You will use real texts in these examples instead of the infamous Lorem Ipsum. - Make it easier to read:
A “TL;DR” is quite valuable for anyone wanting an overview of a component. A quick introduction with the main points about each element: what it is for, use cases, points of attention, etc.
Have you ever participated in the process of creating a Design System as a UX Writer?
Tell me how it was!
