Skip to main content

Descriptions

Descriptions provide further details about a given entity, to help users advance, while reducing liability.

Tone and Voice#

We trust to be trusted. We're serious, and we never alarm users, we soothe their anxieties. We add descriptions to deliver transparency, so users are aware of liabilities, and sensitive information. We want to add precision with descriptions, and not trigger doubts. We're reliable, we mean what we say. After reading our descriptions, users should feel confident about what actions they want to take.

👍 Dos#

  • Make descriptions as scannable as possible. Users usually skim through, or skip descriptions entirely.
  • Descriptions should be clear, never ambiguous.
  • They should be present anywhere there's a sensitive action taking place. Make sure the user understands the implications of changing a setting, for example.
  • When adding definitions, always use our Glossary as the source of truth.

Grammar#

  • We encourage the use of possessive adjectives or pronouns in sentences, as long as they don't exceed the limited space for text, in the UI. They reinforce the idea that users should feel connected with their VTEX environment, and feel they belong. It shows the respect we have towards their store.
  • Prefer direct sentences, without passive voice.
  • Use sentence case.
  • Add punctuation at the end of sentences. Use exclamation marks carefully.
  • Maximum of 2 sentences. Break down longer sentences if it adds clarity.