Liferay Style Guide

The Liferay Style Guide sits on the shoulders of giants—specifically, the giants of The Chicago Manual of Style and Strunk and White’s The Elements of Style. Where this guide is silent, assume what is written there. Both of those style guides are the foundation for what is here; in fact, this guide would not be possible without them.

Liferay’s documentation style comes from four overarching values:

1. Documentation is Comprehensive: it shows everything you need to know about the software.

2. Documentation is Concise: it gets to the point and avoids fluff.

3. Documentation is Cohesive: individual documentation relates to an overall message.

4. Documentation has Clarity: it is written to make the message as clear as possible to the largest number of people.

Comprehensive Documentation

Liferay’s documentation is organized in a way that shows what concepts are available and how to navigate them. A person should be able to browse as easily to a particular topic as search for it. We achieve this by organizing it in ways that correspond to solving goals. Documentation has several layers. At the foundation is feature documentation that describes every feature Liferay’s software has to offer. Sitting on the foundation is conceptual documentation. Consisting of well-designed introductory text, it builds on feature documentation by describing ways features are used.

Concise Documentation

We work hard to make Liferay’s documentation concise. By keeping paragraphs short, using bulleted lists when possible, and avoiding long exposition, we keep to the subject matter. Our aim is to make it as easy as possible to digest the content. We use short, easy to understand descriptions, diagrams, illustrations, and even video to make this happen.

Cohesive Documentation

Liferay’s documentation is written in a particular style defined in this document. Following Liferay style successfully makes it so many writers have one voice. The more Liferay documentation you read, the more you pick up on how we present information, and this consistent style makes it easy to learn, because you know what to expect.

Clear Documentation

To be effective, documentation must be clear. We work hard to make the message communicated equal the message received, and the methods for doing this are outlined in these standards.

Additionally, the documentation has a single goal: to teach Liferay concepts as effectively as possible. We use consistent examples and use cases throughout the documentation, to make the documentation as a whole fit together as one. Documentation in different styles (introduction, concept, feature, and reference) complement each other by communicating Liferay’s functionality in different ways for different learners.

You

Despite all the effort we spend to define the different types of documentation described above, the standards you’ll see below for making communication clear, and the workflow we use to ensure Liferay style is followed, we can never know if we’re successful without you. The standards described here are the result of many years of defining, testing, and refining our content, but since no human is perfect, there are certainly ways they can be improved. If something isn’t clear or doesn’t sit right because of one of these standards, we encourage you to send us that feedback through Liferay Discuss.

Rule Priorities

Not all rules carry the same weight. When applying these guidelines—whether as a human writer or an automated tool—use the following priority levels:

• Must: The rule is mandatory. Violating it produces a clear error. Examples: no future tense, always use Oxford commas, do not project roles onto readers.
• Should: The rule establishes a strong preference. Deviations require a specific justification. Examples: avoid “simply” and “just,” prefer plural constructions over singular-they.
• May: The rule reflects 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 below.

Rule Scope

Most rules in this guide apply to all documentation types: Introduction, Concept, Feature, and Reference. The following rules have narrowed scope:

• No “we,” no “let’s”: Applies to all reader-facing documentation. 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 doc types.

Known Exceptions and Tie-Breakers

Where rules appear to conflict, apply the following resolutions:

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 the Chicago Manual of Style. Prefer the plural construction for clarity; 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.