Liferay.Design / Lexicon
/
Get Started
    Writing
Resources
Part of Liferay, IncCode/Content Licenses

Writing Framework

Sign In
DocumentationPending

Be clear and concise

Always include information that helps users understand the interface better. However, remove irrelevant ideas, details, or words if it adds more noise to their workflow.

Keep sentences short

Try to limit a sentence to less than 20 words


Selecting an application will copy its data to staging. Staged content may not be editable in a live environment.


Do

When an application is checked, its data is copied to staging and it may not be possible to edit them directly in live.


Don't



Don't speak abstractly

Use concrete words to convey ideas. Avoid abstract words that can be left to interpretation.


Your A/B test has declared a winner.


Do

Your A/B test is successful.


Don't



Reveal information as needed

Provide just enough information to safely and effectively complete the task at hand. Don’t complicate the task by worrying what could happen down the line.


Events screen

This is the data model of events sent to Analytics Cloud.


Hidden events tab

This event has been set to hidden due to 30 days of inactivity.


30 days prior to deletion

Inactive events will be automatically deleted in X days.


Do

This is the data model of events sent to Analytics Cloud. Inactive events will automatically be set to hidden after 30 days of inactivity and removed if inactive for the duration of the retention period.


Don't

Use an active voice (mostly)

An active voice is more clear, direct, and easy to read. With an active voice, the subject performs the action. Use an active voice when writing longer messages.


Subject-Verb-Object format


Your workspace supports custom time zones...


Do

Custom time zones are supported by your workspace...


Don't


This publication contains conflicting changes that must be manually resolved before publishing...


Do

Conflicting changes that must be manually resolved before publishing are contained in this publication...


Don't


Passive voice delivers a concise message that sounds better when omitting the subject. Use a passive voice as a response to an action or to soften negative statements.

Object-verb format


Download complete.


Do

You have completed your download


Download completed by you


Don't


15 pages deleted.


Do

You have deleted 15 pages


15 pages have been deleted by you


Don't


Write at a lower reading level

Writing at a lower reading level provides a better accessibility and reinforces the user experience.

  • Use natural language that is easy to understand. Using big words can communicate less credibility and lack of confidence.
  • Avoid industry jargon.
  • Consider whether someone in middle school can understand the concept.

Segments group your users together by properties or behavior.


Do

Segments cluster users together using classification taxonomy or DOM events.


Don't


Make your content scannable

Users of digital products tend to scan the interface for keywords until they find an area of interest. To improve their experience, we must optimize our content to be easily digestible and scannable.


Break up long blocks of text

  • Long paragraphs to multiple shorter paragraphs
  • Long sentences to multiple shorter sentences
  • Short paragraphs to a list format
  • Headings to break up content blocks

Make keywords stand out

  • Start a phrase or sentence with the objective rather than the action they need to take. This helps the user scan the content.
  • Include meaningful keywords and phrases

To filter the web content list by a structure, select a structure.


Do

Select a structure to filter the web content list by a structure.


Don't

Use the positive form of a sentence or a phrase

Positive language emphasizes what the user can do rather than what they can not. It is more actionable and creates a more positive emotional response from the user.

  • Avoid negative language
  • Avoid sarcastic language

You’re done with all your tasks.


Do

You don’t have any more tasks left.


Don't


Something went wrong. Our team of experts are already working to resolve it.


Do

Hurray, we found another error. Someone will fix it (hopefully).


Don't

First person vs second person

We instill trust in our products by personifying and humanizing the interface with our writing. To accomplish this, it is important our communication sounds conversational and collaborative.


When referring to Liferay, we use the first person: we, us, our, ourselves.


We weren’t able to find your ship-to address. Please update it in your account profile.


Do

Liferay wasn’t able to find your ship-to address. Please update this in your account profile.


Don't



When referring to Liferay products, we use “it.” This may relate to marketing copy more than in the product.


Analytics Cloud serves as a single source of truth for user data. Use it to discover, measure and optimize your digital experiences.


Do

Analytics Cloud serves as a single source of truth for user data. We help you discover, measure and optimize your digital experiences.


Don't



When referring to our user we use the second person, most of the time.

  • You, your, yourselves
    • Refrain from over-using second person pronouns such as “your segment list.” We should avoid using pronouns if it doesn’t enhance the user’s understanding.

Create and train your recommendations


Do

Create and train my recommendations

Create and train our recommendations


Don't


Navigation items:

Segments

Account

Profile


Do

.

Your Segments

Your Account

Your Profile


Don't



An exception is when our user is directly responding to a question in our UI.

  • I, my, me
    • Legal requirements related to consent
    • Refrain from using My XYZ even in navigation, as it implies that the product is an extension of the user rather than a tool. This also makes it harder to facilitate a conversation with the interface.

Check the box below to confirm your intentions:

[x] I consent to sending usage data to help improve this product.


Do

Check the box below to confirm your intentions:

[x] You consent to sending usage data to help improve this product.


Don't



Use third person pronouns when referring to someone other than the user.

  • Be gender neutral in the reference. Use they, their, them.

[email protected] has not accepted their invitation to join this workspace. Resend email?


Do

[email protected] has not accepted his invitation to join this workspace. Resend email?


Don't


Use simple verb tenses: present, past, and future

The use of simple verb tenses makes communication easy and less verbose.


Data sources syncing

Data sources will sync

Data sources synced


Do

Data sources has synced

Data sources will have synced

Data source had synced


Don't


Consider localization

Our products are used by an international audience. We want to be considerate to the users and translation services.

Use American english styling to maintain consistency for our translation services


1,000,000.00


Do

1.000.000,00


Don't


Jan 1, 2021


Do

1 Jan 2021


Don't



Avoid local and colloquial phrases


This may be difficult to understand.


Do

This may be difficult to wrap your head around.


Don't


Examine your events data to discover usage patterns.


Do

Weed through your events data to discover usage patterns.


Don't


Something to improve? Report an issue!
Menu