Core Style

Liferay produces documentation, courses, and instructor-led training for many readers in many situations. The same voice and the same word choices appear across all of them. 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. Instructor-led training reverses several rules here, because a talk track is speech; see Instructor-Led Training.

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.

Each rule states its own strength in its own words. Never and Do not mark a rule with no exceptions; Prefer and Avoid mark a strong default that a specific reason can override.

Some rules are checked automatically by Vale, which reports a finding on a pull request. How loudly Vale reports one is a separate question from how serious the violation is, because it also depends on how reliably the check can tell a real violation from a legitimate exception. A rule with no exceptions can still report as a warning when its check produces false positives.

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, direct, and measured. 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 exist to enforce that directness: no future tense, no “simply” or “just,” and no “the following” without an object.

Measured

Lead the reader into a point rather than confronting them with one. Prefer observational framing over absolute or combative claims, in titles and in body text.

Bad: Every Custom Module Is a Future Upgrade Cost

Good: The Upgrade Cost Hiding in Your Custom Code

The first reads as a challenge before the reader has any context. Cut punchy aphorisms, dismissive asides, and imperatives aimed at the reader such as “sit with that.” Being direct means getting to the point, not sharpening it into a provocation.

The same habit shows up at sentence level. Watch for verbless fragments used as punchlines, stock openers such as “Fair warning,” and one rhetorical device recycled through a whole article.

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…

Do not project an opinion or reaction onto the reader either. Presuming what the reader thinks, then correcting it, puts words in their mouth.

Bad: This branch isn’t a leftover. The transformer receives configurations for both editor versions.

Good: The transformer receives configurations for both CKEditor 4 and CKEditor 5 editors.

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 Drop “Can”

When you describe something the reader is able to do, keep can. Dropping it turns a capability into a command or a flat statement of fact, and the meaning changes.

Bad: You define the fields on the object.

Good: You can define the fields on the object.

Use the imperative when the reader is performing a step, because there a command is what you mean:

Good: Define the fields on the object, then click Save.

The test is whether the sentence describes an option or an action the reader is taking right now. An option keeps can.

Don’t Hedge Software Behavior

Describe what the software does, not what it might do. Hedging words such as should, may, might, and 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.

Avoid Overloaded Sentences

Convoluted writing comes from overly complex sentences that stack too many elements (e.g., a main clause, an aside, and an appositive). Including too many ideas in one sentence overburdens the reader. Split these sentences.

Never include more than two core ideas in a single sentence.

Bad: The transformer also appends a separator ('|') and 'style' to the toolbar’s items, but only when style isn’t already present, so the Styles drop-down always appears in the toolbar.

Good: The transformer also appends a separator ('|') and 'style' to the toolbar’s items when style isn’t already present. This ensures the Styles drop-down always appears in the toolbar.

Lead with the Subject and Verb

Do not bury the subject or the verb. A long opening clause delays your main point, and overloading sentences with parenthetical appositive clauses interrupts the flow.

Bad: Because the transformer works only with the configuration object and standard DOM APIs, the extension needs no @ckeditor package.

Good: Including a @ckeditor package isn’t necessary because the transformer works only with the configuration object and standard DOM APIs.

Phraseology

American Spelling

Use American spelling. Write color, behavior, organize, and license, not colour, behaviour, organise, or licence.

Sentence Spacing

Put one space after a period, never two.

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, with 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

Never use an em dash. Rework the sentence instead: split it into two sentences, or use a comma or a period.

Bad: Price lists set the unit price — promotions adjust it later.

Good: Price lists set the unit price. Promotions adjust it later.

Reaching for a dash usually means the sentence is carrying too much. Removing the dash exposes the construction it was hiding, which is why this is a phrasing rule and not only a punctuation one.

Use 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.

Descriptive link text stands on its own; do not append a trailing phrase (for example, “for details” or “for that flow”) after the link, which adds nothing the link text does not already convey.

Internal Tracker References

Use Liferay Jira ticket references such as LRDOCS-XXXXX, LPS-XXXXX, LPD-XXXXX, and COMMERCE-XXXXX 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, as in “The schema is created automatically; you don’t need to run a script.”

Vague Qualifiers

Remove qualifiers that do not add meaning, such as currently, still, and both:

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.

Historical Framing

Describe how the product works now. Drop formerly, used to, previously, and as of the last release. They age badly and add nothing for someone reading today.

Bad: The setting was previously found under Instance Settings, but it now lives under Configuration.

Good: The setting is under Configuration.

The exception is content whose subject is the change. Deprecation references, breaking-changes pages, and upgrade articles exist to tell the reader what moved, and there the history is the information.

Jargon Nouns

Do not use surface as a noun meaning a place in the product, and do not use exercise to mean test or run. Both hide the specific thing the reader must identify. Name the thing, or use the plain verb.

Bad: The key belongs to a bundled Liferay surface.

Good: The key belongs to the rich text editor in page fragments.

Bad: To exercise the Alloy Editor branch, change the key.

Good: To test the Alloy Editor branch, change the key.

Both are the same habit: a plain word repurposed as a technical noun. The other form is a noun pressed into service as a verb, as in to action a request or to sunset a feature. Both read as in-group shorthand to anyone outside the team that coined them, and the plain phrase is faster to read.

Invented Words

Don’t invent vocabulary. De-risk is the type case: it isn’t in general dictionaries, and readers don’t use it.

Bad: Staging de-risks a large content change.

Good: With staging, you can review a large content change before it goes live.

Ordinary professional vocabulary is fine and is not the target. Leverage, robust, unblock, and exemplar all read as normal English.

Figurative Language

Describe what happens, not a metaphor for it. If a reader can ask “what does that actually do?”, the metaphor is carrying meaning it cannot deliver.

Bad: The CKEditor 4 handler wipes the editor’s toolbar.

Good: The CKEditor 4 handler returns a toolbar CKEditor 5 cannot interpret, so the editor renders with no buttons.

Bad: The heart of the transformer is the entry it adds to style.definitions.

Good: The transformer adds one entry to style.definitions.

Verbs That Hide the Result

When a verb describes an operation, say what the operation produces. Words like normalizes, handles, and processes name an activity without telling the reader what comes out of it. A bare returns has the same problem, because the object is where the information is.

Bad: The existingItems variable normalizes the toolbar configuration.

Good: The existingItems variable holds the toolbar’s item names, whether the configuration is an array or an object.

Bad: The branch replaces the toolbar and returns.

Good: The branch replaces the toolbar and returns the modified configuration.

Noun Stacks

In a stack of nouns, the rightmost modifier binds tightest to the head noun. Editor sample application groups as “editor sample” plus application, which reads as a sample the editor produced. Put the word that classifies the head noun outermost, and prefer breaking a three-noun stack apart.

Bad: one of Liferay’s editor sample applications

Good: one of Liferay’s sample editor applications or one of Liferay’s sample applications for editors

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.

Unclear Referents

Don’t use it, this, that, or here unless what the word refers to is obvious and close by.

Bad: Traditionally a developer builds all of it by hand.

Good: Traditionally a developer builds the form, the validation, and the persistence layer by hand.

Two related habits. Prefer which requires or this requires over a vague that means. And here needs a place the reader can see, so avoid “right here in the interface” on a page with no shared screen.

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, courses, and training (for example, Designed To). These are stated separately in each type file’s Phraseology section rather than here; core covers only the shared phraseology.

Instructor-Led Training

Instructor-led training is a third content type. Its full standard lives with the training source rather than in this guide, because most of it concerns slides and talk tracks. A talk track is speech, so several rules here reverse in a classroom:

Rule	Documentation and courses	Instructor-led training
Future tense	Forbidden	Required for pointing ahead (“tomorrow we move to…”)
Contractions	Encouraged	Required
“We” and “let’s”	Avoid	Expected, for the shared journey
“Simply” and “just”	Never	Relaxed for natural spoken cadence, but never to minimize genuine difficulty
Role projection	Forbidden	Naming the audience’s role is correct; projecting feelings or skill is not

Everything else in this guide carries over to training, including the Oxford comma, the terminology table, alt text on every image, and must over need to.

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.