Skip to main content

Getting Started

What is UX Writing#

"An experience with broken words is a house with broken walls. Fix the words as you would repair the walls." - Torrey Podmajersky, Strategic Writing for UX, published by O'Reilly Media, Inc. in June 2019

UX Writing is the craft of designing the words that users see and interact with, in softwares. It is a vital component within the general user experience we want to promote to our clients. Text written in screens is often referred to as microcopy, for we have very limited space to convey actions and concepts.

Where can you find UX Writing, in our VTEX context:

  • Our VTEX Commerce Admin
  • VTEX IO apps and Toolbelt
  • Our stand alone products, like VTEX Tracking
  • Our platform status page
  • APIs

What UX Writing is not#

UX Writing is not the same as creating content for websites, social media, or documentation. Likewise, this styleguide is not a general guide for copywriting. It is specifically for microcopy that is seen on our VTEX platform's UI, or APIs that developers interact with.

Who is this styleguide for?#

UX writing is a collaborative craft in its essence.

In VTEX, we have different teams who collaborate to create the words on our experience. People from Localization, Design, Product and Education teams usually take part in the UX Writing process.

We build for community. If you are writing the text that appears on our VTEX platform's UI, this styleguide is for you. It is the resource that everyone involved in UX Writing can count on, to create precise copy, aligned with our tone and voice, following best practices.

We might have different tools to accomplish our goals, but at the end of the day, we want the same thing: to facilitate an intuitive experience for VTEX customers. A shared responsibility means we tackle the challenge together, co-create the resources needed, and scale the access so we have agile processes.

This guide was developed seeking to educate our community about UX Writing in VTEX's context, with no commercial intention.

Why follow UX Writing guidelines#

By defining clear UX Writing guidelines, we wish to:

Avoid#

  • Inconsistent terminology: a unified information architecture is vital when designing text. Terms must have contextualized, unique meanings, that are consistent throughout our platform.
  • Lack of alignment with our brand's voice: users must recognize us regardless of the medium they're interacting with. Our brand's voice and principles must be taken into account in UX Writing.
  • Ambiguous microcopy: we must be precise with UX text, so our users know how, when, why and what actions they need to take.
  • Frustrating our users: UX copy is what the user ultimately interacts with in a software. We must transmit trust, not trigger confusion.

Achieve#

  • Text aligned with VTEX's goals and brand: UX writing is how our voice can be heard daily by our clients. We must have a strategic approach with microcopy, transmiting our goals, values and brand principles as a company.
  • Clear information architecture: it is the structure for an excellent user experience. Not just within modules, but throughout the whole product.
  • Agility for our user's actions: the effectiveness of UX Writing can be measure by how long it takes for users to achieve their goals on a screen. Our microcopy should promote agility and confidence to users.
  • Polished product: leveraging engineering, design and UX writing so our users recognize our product's reliability and our authority in the market.

How was this styleguide built#

The Education and Design teams conducted an internal research to map how we previously dealt with UX Writing. We identified what frictions were present in our process, and what resources were missing so we could create the best microcopy collaboratively. This styleguide is the result of the research's effort, to improve how we manage UX Writing in VTEX.

Torrey Podmajersky's book, Strategic Writing for UX, published by O'Reilly Media, Inc. in June 2019, has been a major reference for this guide's content and structure. She's been an expert on this field for over 10 years, and you'll see many quotations and concepts from her book here, always directly cited.

What does it contain#

Here you can find:

  • Voice Chart: to guide you in drafting, editing and choosing the best microcopy.
  • Text Patterns: so you'll have a starting point to write precise text for buttons, titles, error messages and more.
  • Process: to direct you to the best practices and steps present when writing microcopy.
  • Accessibility: so we build for community.
  • Localization: to write copy that is ready to go global.
  • Word List: so we have consistent terminology.