Content guidelines

Voice and tone principles

We communicate as we live our corporate values based on helpfulness, transparency, empathy, and orientation, providing a consistent, friendly, helpful guide to our users. We want to build relationships, and how we communicate is a key part of that.

Our tone sounds confident, friendly, and respectful, informing the audience knowledgeable.

We use an informal salutation. In German, for example, we use “Du” with a capital first letter. For greetings, we use the casual “Hello”.

Inclusive language

Inclusive language is free of words, phrases, or tones that reflect disrespectful, offensive, prejudiced, or discriminatory views about specific people.

Do: Lead and sub creditor, allow list and block list
Don't: Master and slave creditor, whitelist and blacklist

Gender

Try to avoid gendered pronouns, otherwise prefer to use they or their instead of his, her, he, or she.

Do: Contact your admin to give you access to the page.
Do: Contact your admin if they can give you access to the page.
Don't: Contact your admin if he or she can give you access to the page.

Writing style

Follow these guidelines to improve clear and brilliant writing:

• Use the active voice.
• Keep it brief by using simple words and short sentences.
• Get rid of filler words and phrases.
• Use consistent terms as not to confuse the user unnecessarily.
• Avoid using abbreviations and acronyms whenever possible.
• Empathize with your reader and don't assume any level of technical fluency from your users.

Localizations & Default Languages

wescale is available in more than 20 languages. Our translators strive to provide the best localizations in all supported languages, enhancing the user experience and fostering trust in our product. By adhering to CLDR standards, we avoid inconsistencies and ensure that numbers, currencies, and dates are accurately represented for users in all locales.

Numbers

Numbers are displayed in a format that reflects the user’s locale, including the appropriate thousand separators, decimal marks, and digit grouping. Quantities must be formatted according to the unit settings and allow as many decimals as specified there.

Do: Germany (de-DE): 1.234,56
Do: USA (en-US): 1,234.56
Do: France (fr-FR): Number: 1 234,56

See: CLDR (Number and currency patterns)

Currencies

Currency amounts are formatted according to the currency type and the user’s locale, which includes the proper placement of the currency symbol, spacing, and precision. It’s important to respect the specific number of decimals per currency. For example, currencies like HUF (Hungarian Forint) and JPY (Japanese Yen) do not use decimal points, as there are no fractional units (like cents or pence).

Do: Germany (EUR): 1.234,56 EUR
Do: USA (USD): 1,234.56 USD
Do: France (fr-FR): 1 234,56 EUR

See: CLDR (Number and currency patterns)

Date Formats and Timestamps

Dates and timestamps must always be formatted based on the user’s time zone and locale. The WUI components WuiFormattedDateTime is already configured to handle this correctly.

Do: Germany (de-DE): 27.04.2024
Do: USA (en-US): Apr 27, 2024
Do: France (fr-FR): 27 avr. 2024

See: CLDR (Date/Time Patterns) and wui (Date and time format)

Languages

American English (en-US) is the mandatory and fallback language across the platform. All localized content must be provided in en-US as the default language. Since wescale is developed with love in Germany, German (de-DE) is our secondary default language, enabled for all customers. For consistency, we adhere to the respective spelling and punctuation rules of each language, with the Duden serving as the reference for German.

Ellipsis / Read more

We try to avoid ellipsis as much as possible for tiny UI elements, such as buttons or chips. For longer texts, however, we can't always avoid truncation by an ellipsis. A possible Read more - button is always on the next line if we truncate a longer text. That way, this function becomes more focus, and the UI looks clearer.
A Read more - button at the end of the line would come with some calculations. The length of the link, depending on the language, or the container's width, depending on the screen size, are just two of many points that have to be considered. Especially if such a link appears many times on one page, this will harm the overall performance and thus the user experience.

Do:

Don't:

Don't:

Related pages
Style guide: When to use which tooltip
Style guide: Utils for line-clamp and overflow-ellipsis

Text highlighting

Bold (strong)

For manuals and help articles, use bold text for clickable UI elements like menu entries and buttons.

Do: System call: Management > Content > Sources
Don't: The Edit button opens the detail page of the webshop.
Don't: System call: Management > Content > Sources

In the UI, emails, and notifications, use bold text to draw the user's eye to object names, message headers, UI elements, and proper names. Use <strong> as HTML tag.

Do: Please order the shopping cart Projects 2022 (#1234567) of John Doe.

If you need to highlight an element, but the UI doesn’t support bold text, use quotations marks instead.

Quotation marks

If you need to highlight an UI element, the preferred form is to use bold text.

If the UI doesn’t support bold text or you want to highlight further text passages in addition to bold text, use quotations marks instead. In our translations, we make sure that the quotation marks are localized.

Do:

Italics

Do not use italics in your web content, as this formatting type is not common in Asian languages.

Feel free to use italics in customer documents, e.g., whitepapers, handouts, and manuals. Hyperlinks don't use italics either.

Monospaced text

Regarding your technical documentation, use monospaced font for names of a file or directory.

In the UI, we only use monospaced text for code snippets, e.g., JSON Path expressions.

Punctuation

Colons

Use colons to start a bulleted or numbered list. Further, use colons if field name and value are not divided into two columns but displayed as text.

Don't use colons in table and form headings.

Do: Manufacturer: Apple Inc.
Do: GTIN (EAN): 123456

Do:

Don't:

Exclamation marks

Exclamatory sentences express strong emotions. Use exclamation marks to bring a touch of positive excitement or emotion to your users.

Don't use exclamation marks, mainly to alert the user to certain occurrences in connection with errors. An error or interruption in the workflow already disturbs the user, so don't make him even more unsure by adding an exclamation mark to a message.

In general, there should only be one exclamation mark per text block.

Do: Welcome to wescale Mobile Shopping!
Do: Congratulations! You are using the right buying channel.
Don't: An error occurred while exporting data! Please try again later.
Don't: The item could not be added to the shopping cart!

Hyphens / en-dash

Ranges are displayed using the en-dash because numbers belonging together are grouped visually and can thus be better grasped as a unit. Don’t use spaces before and after an en-dash. There is one exception: Surround an en-dash with spaces when it's used in a time stamp that includes two times and two dates.

Do: View 1–24 of 15,876
Do: 10/27/21–11/10/21
Do: 8:25 AM–4:35 PM
Do: 10/27/21, 4:35 PM – 11/10/21, 4:35 PM

Not sure if it’s addon or add-on?
Check out our Vocabulary

Oxford comma

Use the Oxford comma, also known as the serial comma, in your documentation and web content.

Do: catalogs, content sources, content channels, webshops, and assignments
Don't: catalogs, content sources, content channels, webshops and assignments

Periods (full stops)

Use periods to complete descriptions, messages, and notifications. Avoid periods in headers, titles, and menu names.

Please don’t use periods in a bulleted list, tooltip, and field description unless the text is a complete sentence.

Uppercase text

Upper case text is difficult to read, therefore, try to avoid uppercase text.

Lists

Use lists to make items easier to scan and follow by the user. Try to limit lists to seven items or less. If you need more, see if you can split the list into multiple lists.

These are the basic list rules for punctuation and capitalization:

• Keep formatting consistent and phrase each item similarly.
• If the bullet points complete the introductory sentence, begin the bullets with lowercase and omit the periods at the end.
• If the bullet points are sentences, capitalize the first word of each bullet point and use periods at the end.
• If the list consists of short bullet points, also do not use periods and capitalize the first word easing the user to scan the list.
• You don’t need to create a list having two or fewer items.

Bulleted list

Use bulleted lists where the order of the items doesn't matter.

Do: Each log entry shows:

• when the change was performed
• who made the change
• what change was made

Do: The following information from your user profile is visible in your public profile to other wescale users:

• Profile picture
• Title
• First name
• Middle name
• Last name

Numbered list

Use numbered lists where the order of the items matters.

Do: To add a new content source:

1. Go to Management > Content > Content sources.
2. Select New content source.
3. Enter the details.

Numbers

Write out numbers one through ten in your documentation. After ten, use the digit form such as 11, 12, 99, 100, 101, etc.

Due to technical limitations, the influence on the displayed numbers in the UI is often less flexible. Try to provide the singular and plural form depending on the number, of course, except for languages that do not use the plural form.

We use MessageFormat to support language-specific pluralization logic. Do you want to learn more about it? Find further information about MessageFormat syntax here or check out the details about language pluralization rules here. Topics of cultural and hidden assumptions components are listed here.

• The shopping cart has been fully ordered with the following purchase order {poNumberCount, plural, =1 {number} other {numbers}}: {poNumbers}
• No item | 1 item | {n} items
• 1 shopping cart item has been added successfully. | {n} shopping cart items have been added successfully.

Pronouns

In most cases, addressing the user in the second person is best. Speaking directly to the reader fits wescale's casual, conversational tone except for certain text types, such as white papers and press materials.

Try to avoid using mine, my, or your in the UI. If you need to use your, my, or mine, think of the UI as a conversation between the system and the user.

Use your if the system is presenting information to the user. If the user is acting, such as clicking a button, you should better use mine or my.

Do: Manage your shopping lists.
Do: My substitutions, My shopping lists, My favorite applications

Articles

Do not use articles (the, a, an) for action-based elements, such as buttons and labels. In more complex sections of the UI, like alerts and empty states, use articles to help and support the users's understanding.

Do: Create shopping cart
Don't: Creating a shopping cart, Creating shopping cart

This site is a living document and is in some places ahead of the platform. We are always trying to implement and adapt wescale content according to the guidelines from this document. The standardization of all content on the entire platform is a real mammoth task and will take some time until completion. Nevertheless, you are welcome to use this document as a basis for your work and feel free to contact us at any time if you have any questions or comments.