VTEX Writing Style Guide for English

Created by: Thalita Sdroiewski Uba

Last updated: 12 de jul.

Welcome, marketing and communication professionals!

This Writing Style Guide was created specially for you. This is the first volume of a series of Style Guides that will ensure consistency across the content we produce at VTEX.

WHY

Our goal here is to improve readability and build consistency to deliver the best content possible to our target audience. That's where the Style Guide comes in: a practical and easy-to-read guide through our writing world. Here, you will find standards regarding tone of voice, punctuation, capitalization, numbers, dates, and terminology, and also some good practices that should be followed by anyone who writes any sort of text on behalf of the company.

HOW

Use it as consulting material whenever you're about to start a new text that falls within the following categories: blog articles, customer pages, ebooks, guides, press releases, social media posts, solution briefs, scripts, whitepapers, and other formats targeted toward external audiences. And don't forget to check it after you're done, when reviewing the text.

WHAT

This guide was written for all marketing and institutional communication professionals that write content for external audiences—earned, paid, or owned media. It does not contemplate internal communication and Product content (yet!).

For further information, please visit the #content Slack channel or contact Thalita Uba via Slack (@thalita.uba) or at thalita.uba@vtex.com.br.

Tone of Voice

VTEX's voice represents our core brand elements in the way we communicate. It ensures that our writing embodies VTEX's personality and quality standards across all touchpoints.

It's really important that our tone of voice is standard throughout the whole company. That's why we need to be perfectly aligned with our brand guidelines.

Tone = Context

Before writing a text, ask yourself: what's the purpose of this piece? Is it supposed to catch people's attention? Do I want to explain a concept or communicate with our clients directly? Am I trying to catch someone's attention or communicating a failure within our platform? Our tone should adapt based on the user's and the message's context. Use the answers as a guide to find the right tone.

Voice = Personality

The Brand team grounded VTEX's personality in three pillars: boldness, trustworthiness, and optimism.

We are bold

We are technology and commerce specialists building our authority in the market. Our boldness lies in our capacity to be provocative, avoid fluffy words, and go straight to the point.

We are trustworthy

We're serious and soothe our clients' anxieties. Our words must convey precision, and not trigger doubts. We're reliable, we mean what we say. Our clients know they can count on us.

We are optimistic

We have many opportunities to explore, and the future is bright. We chase new opportunities, and we don't run away from challenges. Instead, we try to find a solution without pointing fingers at our competitors or audience.

Let's take a look at some examples:

✔️ Take the next step in your commerce journey. Deploy, test, and scale with more agility and less risk with the VTEX Enterprise Digital Commerce Platform.

✔️ Give customers the choice and convenience they want while running an efficient omnichannel operation.

✔️ With over 20 years of digital commerce knowledge, our team of specialists is here to guide you through your journey.

This is what we get when we put it all together:

VTEX is not the hero

The audience is the hero, and VTEX is their guide. We have so much to deliver to the world, and we tend to place ourselves as protagonists. Let's change this approach: when we present ourselves as a guide, we become the help they need to overcome their challenges. Let's see some examples:

Talking to anybody

VTEX's distributed OMS is the solution that empowers ecommerce managers to view their complete commerce operation.

Relatable

✔️ Take control of your entire commerce operation with VTEX's distributed OMS.

Audience-first

It is never about us. We believe that our communication strategy is the most powerful resource to start a conversation, so it's crucial to understand who we are talking to. Are they from a technology or business background? Are they from an operational role or a leadership position? What are their desires and pains? Try to address what our audience is looking for specifically. Avoid generic messages that try to talk to everybody and end up talking to no one. Let's see some examples:

Generic

VTEX launches a new SKU bulk loader that makes it easier to upload hundreds of SKUs to your store.

Empowering

✔️ Uploading hundreds of thousands of SKUs used to take several hours of your day. With the SKU bulk loader, you can have all those hours back.

Simple and direct

Be straightforward. As a complex solution, we already use many concepts and specific jargon, so we must make our texts as clear and direct as possible. Anyone reading our announcements should be able to relate to what we are saying. Also, avoid repetitions and ambiguities. Always re-read your text to make sure there aren't too many repeated or unclear terms/ideas.

A bunch of noise

You can export complete reports with your store's main KPIs and assess if it's the best way to accomplish your organization's objectives.

On point

✔️ Use complete performance reports to keep track of the efficiency of your operation.

Long story short:

✔️ Always know who you are talking to.

✔️ Our audience is the protagonist of every message. VTEX is the guide.

✔️ Keep it simple and straight to the point.

✔️ Find the balance between boldness, trustworthiness, and optimism to achieve the right tone.

Good practices

Readability tells us how clear and accessible our texts are. Content that is easier to understand will be easier to navigate. Thus, a readable text not only pleases Google when it ranks our pieces, but it also pleases the reader.

Here are some rules of thumb for good readability scores:

✔️ Keep your sentences and paragraphs short and concise.

✔️ Keep similar and complementary ideas within the same paragraph.

✔️ Start a new paragraph when you want to present a new idea or point.

✔️ Avoid creating one-sentence paragraphs.

✔️ Use active voice as much as possible.

✔️ Replace long words with short synonyms, if possible.

✔️ Jargon and fancy words should be kept to a minimum.

✔️ Adapt to your audience.

Guidelines

Formats

These are the most common text formats that we produce here at VTEX:

Website content

Article (VTEX Blog/Linkedin)

Customer page (currently us-en/cases/) - follow this template here

Ebooks

Whitepaper (Top-funnel asset)

Guide (Mid-funnel asset)

Customer ebook (Bottom-funnel asset)

Press releases

VTEX press releases

Customer press releases

Videos

Customer script

Internal interviews script

Standard language

The standard language for VTEX content is US English, which means:

✔️ Color

✘ Colour

(No U after O)

✔️ Favorite

✘ Favourite

✔️ Center

✘ Centre

(TER, and not TRE)

✔️ Theater

✘ Theatre

✔️ Centralize

✘ Centralise

(ZE, and not SE)

✔️ Apologize

✘ Apologise

Eventually, some of our content will be adapted to British English, but unless you're writing specifically for this audience, please make sure you're following the American English rules.

Gender-neutral language

You can use the singular "they" as a generic third-person singular pronoun to refer to a person whose gender is unknown or irrelevant to the context.

❗REMEMBER❗

When “they” is the subject of a sentence, it takes a plural verb regardless of whether “they” is meant to be singular or plural. Therefore, always write "they are" (and not "they is").

Stative verbs

Stative verbs describe a state rather than an action. We don't use them in the continuous form.

Here's a list of stative verbs.

agree

hear

possess

appear

imagine

prefer

astonish

impress

promise

be (=part of who you are)

include

realize

believe

involve

recognize

concern

know

remember

consist

lack

satisfy

contain

like

see (=understand)

deny

look (=seem)

seem

depend

love

smell (=have a certain smell)

deserve

matter

sound

disagree

mean

suppose

dislike

measure

surprise

doubt

mind

taste (=have a certain taste)

feel (=have an opinion)

need

think (=have an opinion)

fit

owe

understand

hate

own

want

have (=own)

please

wish

Examples:

This coffee is smelling good.

✔️ This coffee smells good.

He is seeming happy at the moment.

✔️ He seems happy at the moment.

Punctuation

Commas

General rules:

✔️ USE

✘ DON'T USE

To separate independent clauses joined by coordinating conjunctions: and, but, for, or, nor, so, yet.

✔️ Black Friday was over, but the results kept on coming.

Before "because".

✘ You don’t need to create a new policy, because the same one can be used for different sales channels.

After introductory clauses, phrases, or words that come before the main clause, such as: therefore, however, thus, additionally, moreover, furthermore, firstly, lastly, consequently, in conclusion, on the other hand, in the beginning, today, when.

✔️ When the results came, everyone was surprised.

When the subject has two verbs.

We sent our proposal to the client, and scheduled a meeting with the supplier.

Before and after nonessential clauses.

✔️ VTEX, the fastest-growing platform according to IDC, has secured new funding.

Before "so" when you can add "that" after it.

The leaders shared their results, so the employees were all up-to-date.

To separate three or more words, phrases, or clauses written in a series (aka Oxford comma).

✔️ The new product has been adopted in England, Spain, and France.

Between the subject and the verb(s).

VTEX and its partners, have decided to launch the release earlier.

To separate the month and day from the year.

✔️ The company reached its goal on October 3, 2020.

Before and after direct quotations.

✔️ The director said, "Our revenue increased 300% with the new tool", said the director.

Lists

When there is a list of items, use periods at the end of each item, rather than commas or semicolons. Capitalize just the first word, unless they're all titles (books, articles, songs, etc.)

Example:

This is our current action plan:

Exception: Website texts that have a limited number of characters.

Quotation marks

In most content, use double quotation marks (" "), not single quotation marks (' ').

Example: The section title is "Writing guidelines."

Only use single quotation marks when nesting a quotation inside another quotation.

Example: He said, "I told the client, 'You will love the new feature', and I wasn't wrong."

In online content, use straight quotation marks (" "). In printed content, use curly quotation marks (“ ”).

Place closing quotation marks:

Exception:

Dashes and hyphen

A hyphen (-) is a punctuation mark that is used to join words or parts of words only.

An en dash (–) is a punctuation mark that is used to indicate intervals of time or ranges of numbers

An em dash (—) is a punctuation mark that can be used to replace parentheses or a colon to create emphasis in your writing. Do not add spaces before or after the em dash.

Footnotes and endnotes

Footnote or endnote numbers in the text should follow punctuation and preferably be placed at the end of a sentence.

Examples:

✔️ For that same retailer, the average order value (AOV) the retailer sees is about USD 70.

For that same retailer, the average order value (AOV) the retailer sees is about USD 70.

Numbers

Numerals vs. words

If a number is under 10 (including 10), spell it out (e.g. one, two, three, etc.) If it is over 10, write it using digits (e.g. 43,775).

Exception: You can refrain from spelling out numbers under 10 if they are present in the title because having numbers in titles has been shown to increase the click-through rate.

Avoid writing numbers at the beginning of the sentence, but if it’s a must, spell it out.

Example:

✔️ Half / Fifty percent of the shoppers have opted for pick-up in-store.

50% of shoppers have opted for pick-up in-store.

When writing a figure from 1 to 9 (in dates or amounts, for example), don't add a 0 in front of it.

Example:

✔️ The product was released on October 8 for a special price, only USD 9.90.

The product was released on October 08 for a special price, only USD 9.90.

Separators

Thousands, millions, billions, etc., should be indicated with commas (4,000; 10,500, and so on), and decimals should be indicated with periods (0.20; 0.67, and so on).

You can use large number abbreviations for informal pieces the following way:

Currency

When writing money figures, specify the currency first, add a space, then write the amount. Following the guidelines of ISO 4217 (Currency Codes), the symbol used for American dollars should be just "USD". For Brazilian Reais, the symbol used should be "BRL". For Euros, the symbol used should be "EUR". For British Pounds, the symbol used should be "GBP.

For other currencies, please follow the Economist's guidelines.

REMEMBER

Thousands, millions, billions, etc. should be indicated with commas, and decimals should be indicated with periods.

✔️ USD 20

✔️ BRL 100.80

✔️ GBP 3,100.50

✔️ EUR 10,590,800.30

✘ US$ 20 / USD 20$ / $US 20 / $ 20/ $20 USD

✘ R$ 100.80

Dates

We use the month-day-year format.

Use cardinal numbers (one, two, three) rather than ordinal numbers (first, second, third).

Example: Daniel was born on May 13.

Place commas after the day of the week, the day, and the year.

Example: My last day of work was Monday, May 5, 2020.

Time format

Use lowercase a.m. and p.m., with periods. Do not forget to add a space between the time and the a.m. or p.m. If it's an exact hour, no “:00” is required.

Example: 6 p.m. | 6:30 a.m. | 8 p.m.

When a time is given in Brazil time, include the GMT format.

Example: 10:30 a.m. São Paulo (GMT-3).

Symbols

Use space between the number and the unit of measure.

Example: 5 MB

When the unit is a symbol and not an abbreviation (letters), no space is used.

Example: 36%, 5’

Capitalization

Concepts

Some of our most commonly-used words include composable, marketplace, omnichannel, headless, and microservices. Do not capitalize these unless they’re at the beginning of a sentence!

Only use capitalization of words when they imply a concept, rather than something tangible. Some of the concepts we regularly use, coupled with their associated meaning, are:

Titles and headings

Nouns, pronouns, verbs, adjectives, and adverbs should be capitalized in titles and headlines.

Do not capitalize conjunctions, prepositions, and articles.

Always capitalize the first word and the last word of a title, regardless of their category.

Never write a title or a heading in all caps (or any part of a text, for that matter).

Do not use periods ( . ) in titles or headings.

✔️ The commerce platform with the fastest growth rate is VTEX, according to IDC

The Commerce Platform With the Fastest Growth Rate Is VTEX, According to IDC.

If you want to use a colon ( : ) in your title, treat the two parts of your title as one sentence each, meaning both parts should be capitalized using a sentence case.

✔️ Composable Commerce: The new era of digital transformation

If you’re writing a blog article, keep your title under 70 characters to ensure it will be displayed completely by search engines. For ebooks, your title and subtitle (if any) together should not go above 200 characters. You can use this simple tool to double-check the length of your title.

Titles of works

Titles of full works like books, newspapers, ebooks, whitepapers, movies, series, or music albums should be italicized.

Titles of short works like poems, articles, short stories, chapters, episodes, or songs should be put in quotation marks.

Titles of books that form a larger body of work may be put in quotation marks if the name of the book series is italicized.

Abbreviations / Acronyms

There are certain abbreviations and acronyms that we use widely across our content pieces that do not necessarily require an explanation because they’re so well-known. Please use the following spellings:

Application programming interface

API

Business-to-business

B2B

Business-to-consumer

B2C

Business-to-business-to-business

B2B2B

Business-to-business-to-consumer

B2B2C

Business-to-employee

B2E

Buy online, pick up in-store

BOPIS

Coronavirus disease

COVID-19

Direct-to-consumer

DTC

Latin America

LATAM

Microservice-based, API-first, cloud-native, headless

MACH

Order Management System

OMS

Point of sale

POS

Software as a service

SaaS

Stock Keeping Unit

SKU

United States of America

US / USA

If you want to use a less-common abbreviation or acronym, please state the words in full the first time they appear in the text and mention the abbreviation/acronym in parentheses. From then on, feel free to use the shortened version.

Example: European businesses need to now take into account the General Data Protection Regulation (GDPR). The GDPR has been active since 2016 and can bring hefty fines to retailers not abiding by it.

Compound and hyphenated words

As the English language evolves, lots of word associations are becoming compound words. There are three ways to write these: open compound (spelled as two words, e.g. ice cream), closed compound (joined to form a single word, e.g. notebook), and hyphenated compound (words joined by a hyphen, e.g. long-term).

Here are some of the compounds we use regularly that should be written consistently throughout our content:

✔️

Backend

Back-end; back end

blog article

Blog post

Brick-and-mortar (store)

Brick and mortar

Click-and-collect

Click and collect

Digital-first

Digital first

Dropship

Drop ship; drop-ship

Ebook

E-book

Ecommerce

E-commerce

Email

E-mail

First-party (data)

First party; 1st party; 1P

Frontend

Front-end; front end

Microservices

Micro services; microsservices

Pickup in store

Pick up in store; pick-up in store, pickup in-store

Ship from store

Ship-from-store

Third-party (seller)

Third party; 3rd party; 3P

Time to market

Time-to-market

Time to revenue

Time-to-revenue

Whitepaper

White paper; white-paper

Use a hyphen if two or more words are functioning as an adjective before a noun: fastest-growing platform; world-class retailer; user-friendly UX, etc.

Quotes

In blog articles and ebooks, separate customer quotes from the body paragraphs. In PRs and other texts, keep the quotes within the paragraphs.

You may edit quotes, but do not change the message. Generally, quotes are more impactful if they are shorter and direct, so cut out what doesn’t deliver value. You can also alter or add words, but minimally, only to polish the message.

Bolding, italicizing, and underlining

Special emphasis on words/phrases will help your audience easily scan your content. Use bold and italics, but do it sparingly: if everything is emphasized, then nothing truly is. Here are some basic guidelines:

Specific terminology

App x Application

Applications are software programs that perform various functions developed for end-users to accomplish specific computing tasks.

Apps are a type of application software that performs a single function, usually on mobile devices.

Application x Registration

The word "application" refers to a process that may also involve interviews and tests. There's a chance of rejection.

The word "registration" refers to a process in which you fill in a form, send your documents, maybe pay a fee, and then get the confirmation of your enrollment. There's no chance of rejection.

Click vs. Click on vs. Click at

Click is about pressing a mouse button to select a link or item on the screen. Use "click" as a transitive verb that acts as an action verb and has a direct object—this means that no preposition is required after the verb.

✔️ To save changes made to the parameter settings, click Save.

In the Parameter Details column, click on the Edit button.

Collaborative commerce

Do not use the expression "collaborative commerce" in any of your texts.

Commerce expert x Commerce specialist

Avoid using the expression "commerce expert". Instead, use "commerce specialist."

Data

Treat “data” as a singular noun.

Especially x Specially

Use "especially" in the sense of "mainly."

Use "specially" in the sense of "for a particular purpose".

Future-proof

Do not use the expression "future-proof" in any of your texts.

SKU

SKU can be pronounced as individual letters or as a syllable. This changes the form of the indefinite preposition that should precede it.

An “S”-“K”-“U” / A “SKU”

We assume the “SKU” pronunciation and use the article “a.

Live shopping

When talking about the concept, please only use "live shopping". See how we got to this naming convention here.

✔️ Live shopping

✘ Live commerce

✘ Livestream ecommerce

✘ Any other term combination

log-in-to-vs-log-into

Log in is a phrasal verb that means that you connect to a machine (such as a host, server, workstation, and so on) or authenticate to a user interface by providing your credentials. In this case, "to "is a preposition that links the phrasal verb to the upcoming word.

That is why the correct spelling is log in to not log into.

✔️ Log in to the VAO UI as a VAO Administrator or Plan Author.

Log into the VAO UI as a VAO Administrator or Plan Author.

✔️ Log in to the machine where Veeam ONE Monitor Client is installed.

Log into the machine where Veeam ONE Monitor Client is installed.

VTEX

Company name

We always write "VTEX" in all caps.

Likewise, our official solution should be referred to as VTEX Commerce Platform.

Tagline

Our tagline should always be The Enterprise Digital Commerce Platform.

Boilerplate

About VTEX

VTEX (NYSE: VTEX) is the enterprise digital commerce platform where forward-thinking CEOs and CIOs smarten up their investments. Our composable and complete platform helps brands and retailers modernize their stack and reduce maintenance costs by rapidly migrating from legacy systems, connecting their entire value chain, and making inventory and fulfillment their strength.

As a leader in digital commerce, VTEX is trusted by more than 2,600 B2C and B2B customers, including Carrefour, Colgate, Motorola, Sony, Stanley Black & Decker, and Whirlpool, having over 3,400 active online stores across 38 countries (as of FY ended on December 31, 2022). For more information, visit www.vtex.com.

Brands & Companies

Here’s a list of VTEX brands and companies and their official names. Do not deviate from them:

Events & Educational Programs

Here’s a list of VTEX events and programs and their official names. Do not deviate from them.

COMMEX

VTEX Code Cup

VTEX Internship

DCS

VTEX Connect LATAM

VTEX Lab

DCX

VTEX DAY

VTEX Talks

EICOM

VTEX Gran Prix

VTEX Training Day

TETRIX

VTEX Hackathon

VTEX Accelerator

VTEX Immersion

Products

Here’s a list of VTEX products and their official names. Do not deviate from them.

VTEX Assisted Sales

VTEX Intelligent Search

VTEX Shipping Network

VTEX Conversational Commerce

VTEX Live Shopping

VTEX Smart Checkout

VTEX Extensions Hub

VTEX Personal Shopper

VTEX Store Framework

VTEX Insurance

VTEX Pick and Pack

VTEX Tracking

VTEX IO

VTEX Sales App

Teams and Roles

Generally, refer back to the org chart on Workday when mentioning an internal role.

Capitalize teams. Do not capitalize roles unless it's an abbreviation of a C-level role (such as CEO, CFO, etc.)

Examples:

✔️ Lucas Bacic, head of Core Marketing, led the initiative.

✔️ Santiago Naranjo, CRO of VTEX, said the results were great,

When referring to Mariano and Geraldo, always use their full titles:

✔️ Mariano Gomide de Faria, founder and co-CEO of VTEX

✔️ Geraldo Thomaz, founder and co-CEO of VTEX

Toolbox

Grammarly

Grammarly is an AI-powered writing assistant that checks your spelling and grammar and also offers writing suggestions. You can even add it as a Google Chrome extension! Go to the #grammarly Slack channel to sign up for Grammarly Premium access.

The Free Dictionary

The Free Dictionary is a pretty useful tool for confirming the meaning of words and finding synonyms and new words in general. You have access to Thesaurus, Wikipedia, a legal dictionary, an acronyms dictionary, and more within it.

Statista

For data-driven content pieces, you can use Statista to enhance your findings and provide statistics on market trends and consumer data. We have limited data to premium statistics, but do get in touch with us to obtain the data you’re looking for!