Building UX Writing Guidelines for Enterprise Design

Chhavi Shrivastava
Oct 3, 2019 · 5 min read

Making our product sound a bit more human.

Imagine you are the designer on a project. You have spent weeks understanding your user, perfecting the flows and moving the pixels around. It’s going all good…until someone pings you.

Hey, I need to show this 3-line error message on this tooltip. Can you make it shorter? Also, can I use an “OOPS!”?

Wait, but why? Why can’t an error message be clear, crisp and concise? Who is making sure it sounds like a human wrote it? How do we justify we don’t use an oops?!

In the hustle-bustle of multiple projects, you pause and you look around at all your fellow designers and processes. You are designing experiences for the tiniest of details. But are you missing something?

We landed up in a similar situation a few months back. We all paused and looked at the words on our interfaces. Words that tell our users what went wrong in an error message. Words that help our users navigate through crucial tasks like preparing a disaster recovery plan. Or words that simply tell them, all’s good.

Experience design starts with words; words that ask and answer a question. How do you want to make someone feel? What message do you want to send? What behaviors do you want to encourage?

And this is how our journey of writing better words for our interfaces started. If you are on a similar journey or looking forward to starting one, we hope you find this blog helpful!

The first question to answer is — for whom? If we wrote a set of guidelines for words, who is most likely to refer to them?

Content strategy focuses on all aspects of product messaging — emailers that you send out, the description of the app on the app store, marketing, etc. We decided to scope down our efforts to words that are present on our product interface, aka microcopy.

For our team, our goal was to build a single source of truth for those who write product copy — Designers, Product Managers, and Developers. If for you, the brand design team and product design are the same, additional roles that will benefit from this are — Marketing and Sales.

We then moved on to — the why. Why are we planning to invest in building our own UX writing guidelines? Will it be really helpful, or will it end up being just another section of our design system?

To establish a set of whys, we decided to get a lay of the land. Content audits play a crucial role here. We know, we know. It might sound like a tedious process, and product content doesn’t live in a single place like traditional web content.

While we audited our content manually using our good old spreadsheets, there are plenty of tools and step-by-step blogs to conduct one efficiently.

Here is a sample of the spreadsheet we used for our content audits.

This excel sheet will test your patience, but it will be worth it!

Apart from auditing content, we also audited our design processes to identify the gaps.

How is the product content transferred between product managers, designers, and developers? Does everyone on the team have the same understanding of the flows and edge cases being built? Are we designing for screens or for dynamic user flows?

Conducting an audit of words and on our products, as well as processes around it, gave us our answers to “the why”. To start with we decided to focus on three areas.
1. Inconsistent grammar and syntax
2. Unthoughtful, non-actionable error messages
3. Drab empty states

Look around in your product, you might spot these too!

Now is about a good time to start talking about product voice and tone. UX writing can survive with the fundamentals, but it can thrive with brand voice.

For a consumer-grade product, one is more likely to have a set of well-defined voice and tone. When it comes to enterprise, the users are considered to be more “serious”.

We need even more thought behind an enterprise product’s voice and tone because a human is using that product as part of his day-job, spending hours on it daily. Nobody minds a well-written message with an apt sense of humor.

“If our product was a person, what would it look it” — The persona helped us establish voice and tone.

Starting with a few adjectives that define your product is a good place to start. This will also help you shape the guidelines around the use cases your product team will be handling.

For example, Shopify pivots their examples, vocabulary and actionable language around their merchants. MailChimp with its content guidelines focuses on talking about the people, for the people.

With this, we decided to start writing our holy grail for words. Some useful tips from our side:

• Sometimes the principles become too abstract to use in day-to-day usage. While creating guidelines, it’s a good idea to explain how, and why those principles add value to the writing.

• Use screenshots or product use cases as examples of the guidelines
• Craft your guideline keeping in mind that some folks are there to read them, but most of them are looking for just that one thing. Proper navigation and an accessible location are a must!

At this stage, one might think the difficult part of writing the guidelines is over. If only that were true!

Setting up processes around content and making sure, that the guidelines are not stagnant is equally important. We have come up with processes that work for our team to make sure we review and craft our product copy thoughtfully.

To make sure all the hard work of writing a guideline is put to use, finding a process that suits your team size and releases cycles is a journey you would have to take.

While reading this, you might have wondered. But we don’t have a dedicated content strategy team? Well guess what, neither do we. We had a bunch of enthusiastic designers (read, I and Paul DiGioia) with a passion for writing. We took upon designing our content guidelines like a design challenge. For starters, you can do the same!

We are One team located in San Jose, San Francisco, Berlin, and Bangalore. We are constantly striving to create the right environment that supports great design outcomes. If this resonates with you, join us!

Nutanix Design

Nutanix Design

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store