Core Style

Liferay produces documentation and courses for many readers in many situations. The same voice and the same word choices appear across both. This article defines that shared voice, the phraseology rules that keep prose tight and predictable, and the universal principles that govern how content is organized.

For text formatting, code blocks, lists, tables, headings, images, and admonitions, see Formatting. For rules that apply only to product documentation, see Documentation Style. For rules that apply only to courses, see Course Style.

How to Use This Guide

Liferay’s style sits on the shoulders of giants — The Chicago Manual of Style and Strunk and White’s The Elements of Style. Where this guide is silent, defer to those.

Rules carry different weights:

• Must: Mandatory. Violating it is a clear error. Examples: no future tense, always use Oxford commas, do not project roles onto readers.
• Should: A strong preference. Deviations need a specific justification. Examples: avoid “simply” and “just,” prefer plural constructions over singular they.
• May: A convention or best practice where alternatives are acceptable with good judgment. Examples: contraction use, editor choice.

When two rules conflict, prefer the more specific rule. For known conflicts, see Known Exceptions and Tie-Breakers.

Voice and Tone

The voice is friendly, casual, and direct. Many writers contribute to Liferay’s content; the voice should sound like one person across all of it.

Friendly

Prose should be welcoming. Liferay integrates with many products and services, and they should all be treated equally. Liferay is never compared to any other product, and care should be taken not to assume the use of any particular integration product. Give examples generically:

To finish setting up the Foo Engine, set -Djavax.net.fooey=fooey:verbose in the application server’s JVM. In Tomcat, the option is added to CATALINA_OPTS in setenv.sh:

CATALINA_OPTS="$CATALINA_OPTS -Djavax.net.fooey=fooey:verbose"

Beyond that, avoid documenting other products. In clustering articles, document only what is necessary for configuring Liferay to work in a clustered environment, not the application server itself beyond Liferay’s own Docker containers.

Casual

Write in a casual style so the content reads easily for those for whom English is not a first language. Avoid formality and unnecessarily large words. Contraction use is encouraged to reduce word count and help the text flow.

Direct

You’re addressing one reader, and that reader has work to do. Get to the point. The Liferay Phraseology rules below — no future tense, no “simply” or “just,” no “the following” without an object — exist to enforce that directness.

Address the Reader

Always use you (or the implied “you” in imperatives). Never project a role, title, or job description onto the reader.

Bad: Administrators can create the directory.

Good: Create the directory. or You can create the directory.

Bad: Marketers should use Fragments to…

Good: Use Fragments to…

Avoid we in reader-facing prose; do not say let’s [do something].

Exceptions: Meta-documentation such as this style guide may use we when speaking on behalf of Liferay as an organization. Named UI element labels are reproduced exactly as they appear, even when the label contains otherwise-prohibited words (for example, a button labeled Let’s Go! in a series).

Software Is Not in Control

Empower the reader, not the product. The reader does things; the product is the tool.

Bad: This feature lets you create a record.

Good: You can create a record. or Use this feature to create a record.

Bad: A dialog pops up that allows you to configure the field.

Good: Use the dialog to configure the field.

Don’t Hedge Software Behavior

Describe what the software does, not what it might do. Hedging words — should, may, might, appears to — mislead the reader when the behavior is in fact known and uniform. Either the software does the thing or it does not; pick one and write it that way.

Bad: Dragging the installer into Eclipse should start the installation.

Good: Dragging the installer into Eclipse starts the installation.

When the behavior really is conditional, name the condition instead of hedging:

Bad: This command may fail on a slow network.

Good: This command fails when the request exceeds the 30-second timeout.

The should and may used to indicate rule levels in How to Use This Guide are a meta-documentation convention and are not subject to this rule.

Active Voice and Present Tense

Use the active voice. Use the present tense; do not use the future tense.

Bad: This action will create a new record in the database.

Good: This action creates a new record in the database.

Steps Rather Than Paragraphs

Whenever possible, break procedural matters into numbered steps rather than describing them in prose. Information buried inside paragraphs is harder to find. Numbered steps also help readers (and Liferay Support) point to the exact step where something went wrong.

Omit Needless Words

This rule from The Elements of Style is the mantra. The phraseology rules below name specific words and constructions that almost always trim cleanly.

Phraseology

Oxford Commas

Use the Oxford (serial) comma in any series of three or more items. The comma before the conjunction prevents misreadings:

I want to thank my mentors, my parents and the President for their help.

Are your mentors really your parents and the President? The Oxford comma resolves the ambiguity:

I want to thank my mentors, my parents, and the President for their help.

Future Tense

Do not use future tense. The present tense almost always works:

Bad: This action will create a new record in the database.

Good: This action creates a new record in the database.

“Must,” Not “Need To”

Must is shorter and stronger than need to. One word beats two:

Bad: To use Assets, you need to have an Asset Renderer and an Asset Renderer Factory.

Good: To use Assets, you must have an Asset Renderer and an Asset Renderer Factory.

“Click,” Not “Click On”

Use click as a transitive verb — no on.

Bad: Click on Save.

Good: Click Save.

Bad: Click on an entity to filter the results.

Good: Click an entity to filter the results.

Never “Simply” or “Just”

Never use simply or just. What may seem simple to you is not simple to the reader, and the words add nothing.

Vague “The Following”

The phrase the following is vague because it has no explicit object:

Bad: Please do the following:

Use a specific construction instead:

Good: Follow these steps: or Do these things:

Avoid “Here Are”

Here are (and here is) is a weak way to introduce a list. Lead with the subject instead.

Bad: Here are the properties that changed:

Good: These properties changed:

Bad: Here are the available options:

Good: These options are available:

Colons

Use colons only after independent clauses. The following uses are incorrect; replace the colon with a comma or restructure:

• Bad: To use an accelerator:
• Bad: To create a Site:
• Bad: For example:

Em Dashes, Semicolons, and Parentheses

Use em dashes, semicolons, and parentheses sparingly. Each interrupts the sentence to hold a clause aside; when a sentence leans on several, split it into two.

Meta-Information

Never write about the documentation:

• Bad: This article is intended to…
• Bad: This series of tutorials walks you…
• Bad: At Liferay, we…

This is filler. Keep pronouns strictly to you and avoid mentioning articles, sections, or formats.

Cross-Link Wording

When linking from one article to another, give the link descriptive text — not “this article” or “click here”:

Bad: For more information, see this article.

Good: For more information, see Friendly URLs.

Internal Tracker References

Use Liferay Jira ticket references — LRDOCS-XXXXX, LPS-XXXXX, LPD-XXXXX, COMMERCE-XXXXX, and similar — sparingly, and only when the linked ticket helps the reader do something on this page. The bar is contextual helpfulness, not visibility (many of these tickets are publicly viewable).

• Helpful — keep: Breaking-changes and deprecation-reference pages cite the specific LPD- / LPS- ticket so a technical reader can trace the change to the underlying code via the ticket’s GitHub references. That’s the canonical valid use.
• Not helpful — remove: An article admonition or cross-link that points at an internal status ticket (“see LRDOCS-XXXXX for the follow-up plan”). The reader can’t act on tracker status; they want the article itself to be correct and up to date.

Default to omitting tracker references in prose. Include them only when, on this page, the linked ticket meaningfully unblocks the reader. When a claim’s source is a published breaking-changes page or another article, link to that page instead.

Numbers

Per The Chicago Manual of Style: write out numbers 10 and below; use numerals for 11 and above.

There are six options.

There are 16 places in hexadecimal.

Subject/Pronoun Agreement

Prefer plural subjects. The plural avoids awkward singular-pronoun choices and usually yields shorter sentences.

Less preferred: Each user sees results depending on their context.

Preferred: Users see results depending on their context.

Singular they is accepted by Chicago, but the plural is clearer:

Less preferred: When a user performs this function, they get feedback.

Preferred: When users perform this function, they get feedback.

“Any”

Most of the time, any can be removed without changing the meaning:

If the theme you are using has no token definitions for style books, any color picker configurations on the page are replaced with color palette configurations.

The sentence reads the same without any. Cut it.

“Automatically” When the Software Acts

When the prose already describes an action the software performs, automatically is implied. Drop it.

Bad: When enabled, Liferay DXP automatically creates a dedicated schema for each new virtual instance.

Good: When enabled, Liferay DXP creates a dedicated schema for each new virtual instance.

The cause-effect chain (“when enabled, … creates”) already conveys that the system acts on its own. The same applies to on its own, by itself, and without intervention — if the sentence already describes the software doing the work, the qualifier adds nothing.

The exception is when automatically draws a real contrast with a manual alternative — for example, “The schema is created automatically; you don’t need to run a script.”

Vague Qualifiers

Remove qualifiers that do not add meaning — currently, still, both, and the like:

Bad: The feature is currently available in the sidebar.

Good: The feature is available in the sidebar.

Bad: The notification is still sent when the condition occurs.

Good: The notification is sent when the condition occurs.

Bad: The notification is sent when both X and Y occur.

Good: The notification is sent when X and Y occur.

Use a qualifier only when it conveys information the reader needs.

Verb-Adverb Combinations and Their Nouns

The verb-adverb is two words; the corresponding noun is one. Keep them straight:

Verb-Adverb	Noun
to break (how?) down	here’s a quick breakdown
to set (how?) up	it’s a graphical setup routine
to log (how?) in	never give away your login

If/Then

In BASIC, if needs then. In English prose, it usually does not. Drop the then.

Verb Construction

Do not split the verb construction:

Original	Preferred
to dynamically display different pages	to display different pages dynamically
can optimally be surrounded by	can be surrounded by optimally

Subject and Referent Agreement

Make sure singular and plural subjects and their referents agree:

Incorrect: A geolocation database contains a mapping between IP addresses and their country of origin.

Correct: A geolocation database contains a mapping between IP addresses and their countries of origin.

Universal Organizing Principles

These principles apply to documentation and courses alike.

Organize by User Goal, Not by Feature

Group content around what the reader is trying to accomplish, not around the name of the Liferay feature that supports it. Goal-led organization keeps the focus on best practices and outcomes rather than feature mechanics.

Bad (feature-led)	Good (goal-led)
Fragments	Page Elements
Liferay Fragments	Modular Page Elements
Using Fragments	Building Pages with Reusable Components
Stylebooks	Site Look and Feel
Liferay Stylebooks	Customizing Site Themes
Creating Stylebooks	Applying Brand Styles
Objects	Custom Data Models
Liferay Objects	Modeling Data Structures
Creating Custom Objects	Extending Liferay DXP

This principle was originally articulated for course content, but it applies equally to feature articles in product documentation.

Happy Path First

The first time the reader performs a task, walk them through the simplest, most recommended path. Save edge cases, advanced configurations, and alternative tools for later sections. A reader who completes the happy path first has a working result before they branch into advanced territory.

Self-Contained Articles

Each article should stand on its own. Never assume the reader has read another article on the same topic. If a cross-link helps, include one — but avoid language like:

Bad: You may have noticed the Big Red Button at the bottom of the screen in the article on Foos. Here’s what it does.

Good: At the bottom of the form is this other function. Here’s how to use it.

Describe Artifacts Directly

When introducing a config file, properties file, manifest, or any artifact the reader interacts with, lead with what the artifact is and how to use it. Do not describe what another artifact says about it.

Bad: The committed foo.properties files direct you not to edit them.

Good: The foo.properties file documents build flags and defaults. To override a default, create a sibling foo.[user-name].properties file.

The reader cares about the artifact’s purpose and their next action, not about prose in a separate file.

Never “Introduction to…”

Do not title an article Introduction to [Topic]. Title it with the topic itself.

Documentation Is Not Marketing

Describe what a procedure produces in neutral, technical terms. Do not editorialize the commercial implications — for example, do not highlight that a build-from-source path produces Liferay DXP “with no licensing requirements.” Liferay’s commercial messaging is handled on the pricing pages; technical content should not undercut it. If a sentence reads like advocacy for one path over a paid alternative, rewrite or remove it.

Terminology

Keep terminology consistent. When in doubt, look it up.

Wrong	Right
back-end	backend
front-end	frontend
Javascript (or JS or js)	JavaScript
ServiceBuilder	Service Builder
RESTBuilder	REST Builder
openapi	OpenAPI
re-index	reindex
[LIFERAY_HOME]	[Liferay Home]
out of the box	out-of-the-box
Freemarker or Free Marker	FreeMarker
dropdown	drop-down
Liferay Portal (in prose)	Liferay DXP

The last entry is significant. Liferay DXP is the product. The word Portal is reserved for the source repository name (liferay-portal); it should not appear in reader-facing prose.

Rule Scope

Most rules in this guide apply across all content types. The following rules have narrowed scope:

• No “we,” no “let’s”: Applies to all reader-facing content. Meta-documentation such as this style guide may use we when speaking on behalf of Liferay as an organization.
• Named UI element labels: Reproduce exactly as shown in the interface, even when the label contains otherwise-prohibited words. This applies to all content types.
• Type-specific phraseology: A few phraseology rules differ between documentation and courses (for example, Designed To). These are stated separately in each type file’s Phraseology section rather than here; core covers only the shared phraseology.

Known Exceptions and Tie-Breakers

Conflict	Resolution
“No ‘let’s’” vs. a button labeled Let’s Go!	UI element names are reproduced exactly. The label wins.
“No ‘we’” vs. meta-documentation	Meta-documentation may use we as an organizational voice.
Singular they vs. plural construction	Both are grammatically correct per Chicago. Prefer the plural; singular they is acceptable when rewriting to plural is awkward.
Chicago Manual of Style vs. this guide	This guide takes precedence for Liferay-specific conventions. Where this guide is silent, defer to Chicago.

Feedback

If something is unclear or does not sit right, send feedback through Liferay Discuss. The standards here are the result of many years of defining, testing, and refining content, but they are not perfect.