Writing Framework

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

Don't speak abstractly

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

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.

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

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

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.

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

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

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.

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

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.

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.

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

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

Use simple verb tenses: present, past, and future

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

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

Avoid local and colloquial phrases