Created by: Thalita Sdroiewski Uba
Last updated: 12 de jul.
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.
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.
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.
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.
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.
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.
The Brand team grounded VTEX's personality in three pillars: boldness, trustworthiness, and optimism.
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'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 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:
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.
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.
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.
✔️ 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.
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.
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
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.
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 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.
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. |
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.
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:
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.
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.
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.
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:
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
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.
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).
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’
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:
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 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.
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.
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 |
|
|
|
|
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.
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.
–
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:
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.
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 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.
Do not use the expression "collaborative commerce" in any of your texts.
Avoid using the expression "commerce expert". Instead, use "commerce specialist."
Treat “data” as a singular noun.
Use "especially" in the sense of "mainly."
Use "specially" in the sense of "for a particular purpose".
Do not use the expression "future-proof" in any of your texts.
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.
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 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.
We always write "VTEX" in all caps.
Likewise, our official solution should be referred to as VTEX Commerce Platform.
Our tagline should always be The Enterprise Digital Commerce Platform.
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.
Here’s a list of VTEX brands and companies and their official names. Do not deviate from them:
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 |
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 |
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
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!