Select Page


Defining UX writing and product content guidelines

About the project

The company

Pantheon is a SaaS platform for website hosting and development.

The problem

Pantheon designers and engineers needed a shared source of truth for UI copy and in-product messaging. Without this asset, the team risked inconsistencies and misspellings, which hurt the company’s credibility. Work was delayed whenever a team member needed to track down an answer about grammar or formatting.

The solution

Create a set of content guidelines to make language, style, vocabulary, tone, and voice more consistent throughout our product.

collage of writing guidelines - screenshots from Confluence

My role

UX Writer
Project Lead



Research comes first

Every good project starts with research. Before defining Pantheon’s content guidelines, I did the following:


Competitive analysis

How are other technology companies solving this problem?


What type of content exists in the product today? What will we need in the future? What types of limitations or restrictions do we need to work around (ex: space, layout, character limits).


I spoke with team members in Product, Marketing, and Documentation.

Existing insights

What do we already know? In this case, our brand and corporate communication team had already complied some useful information about our audience, which was used to define brand voice and tone.

Key learning

Content guidelines can be expansive and comprehensive, but the Pantheon teams helped me identify a few areas that were highest priority: Voice and tone in the product and style and grammar rules.

Defining voice and tone

Pantheon’s brand team had recently completed an exercise to define brand personality and voice. We use the Pantheon brand voice across all channels—marketing, customer communications, sales presentations, in-product messaging, etc.

I think of the brand like a person. A person has the same voice all of the time, but their tone changes depending on the situation.

Similarly, we must adjust tone to account for specific use cases and match where our audience is at in their journey. This mean defining a specific voice and tone for product content.


Product tone

When including words within the product, we strive to be accurate, brief, clear, and helpful. We also use active voice.

Key learning

The tone in the product should be different than the tone used in marketing.

Defining styles

After defining voice and tone, I needed to shift gears and focus on creating Pantheon’s in-house writing rules. These rules standardize usage and formatting for the words within our product.

The in-house rules are based on our product user needs. For ex: We do not include periods when writing a time (9 am) because we often have space limitations within the product UI, and the periods are not necessary for comprehension.

For writing questions that are not covered by our in-house rules, we default to using what is recommended by the Chicago Manual of Style. We chose Chicago style because it is extremely detailed and well-suited for technical writing.

Key learning

Popular style guides like Chicago Manual and AP Style did not fit our product and content needs exactly. However we can use one as a starting point and develop in-house rules as needed.

Sharing early and often

It was important to share work progress early and often, in order to get valuable feedback from other teams. I brought early drafts of the guidelines to design critiques and squad stand-ups. This not only facilitated fast iteration, but also helped to familiarize other teams with the guidelines before they rolled out. This helped later with adoption and buy-in.

Key learning

When presenting a guideline or rule, it is helpful to explain the guideline AND provide examples. 

screenshot from writing guidelines - how to use active voice
screenshot from writing guidelines - front load the answer


The product content guidelines are now part of Pantheon’s design system. We consider it to be a living document, as we add more guidelines and build out more details (ex: error messages).

For the rollout, I worked with the design systems team to communicate to all of the engineering squads via Slack channels and stand-ups. We leveraged a company All Hands meeting to inform other departments, and we included it in an internal newsletter.

collage of writing guidelines - screenshots from Confluence

Thank you for reading this story!