Liferay Documentation Format

The format, or how a style of documentation is organized, is important to maintaining consistency of experience. As readers make more use of the documentation, the organization of how a feature is presented and described should become familiar. To make this possible, writers must adhere to format conventions.

Never Use the word Introduction in an Introduction Title

In other words, never name an introduction Introduction to….

Make Feature Documentation as Independent as Possible

Each feature article should be as standalone as possible. Never assume the reader has (or might have) read another article on the same topic. If it’s helpful to link to another article, definitely do it, but avoid language like this:

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

Instead, do this:

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

Introducing Steps

When introducing a set of steps, don’t use a sentence fragment as a lead-in. A fragment leaves a dangling construction that reads poorly. You may use a brief, complete context sentence before steps when it adds genuinely useful information, but it’s often clearest to go directly to the first step.

Don’t do this (sentence fragment lead-in):

## Editing Fields

To edit fields,

1. Step one

Do this (steps directly):

## Editing Fields

1. Click the _Edit_ button.

1. Enter a name...

Also acceptable (brief context sentence before steps):

## Editing Fields

Fields can be edited at any time without affecting published content.

1. Click the _Edit_ button.

1. Enter a name...

Comparing Features

When comparing features between items, such as Public and Private Pages, use a table with checks:

| Behavior | Public Pages | Private Pages |
| --- | --- |---|
| Visible to unauthenticated users | &#10004; |  |
| Viewing requires Login and Site Membership |  | &#10004; |
| Distinct URL pattern | &#10004; | &#10004; |

The table above renders like this:

Behavior	Public Pages	Private Pages
Visible to unauthenticated users	✔
Viewing requires Login and Site Membership		✔
Distinct URL pattern	✔	✔

Highlighting UI Elements

Highlighting UI elements is a great way to show users how to use a feature. There are two ways of highlighting UI elements: Box highlighting and numeric annotations.

An example using box highlighting:

Annotate UI elements by drawing a box around them.

An example of using numeric annotations:

Numeric annotations should be paired with definitions of those annotations in the text below.

If you use numeric annotations, define what’s pictured in the text below the image.

Diagrams / Visual Aids

Add diagrams to help users better understand complex concepts, including but not limited to how Liferay features relate to one another, a feature’s purpose/function, or anything else you think may help a reader learn a concept.

Videos

Upload videos to YouTube and then reference them in the article using the YouTube token:

<iframe allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen frameborder="0" height="315" src="https://www.youtube.com/embed/x7fm_nCZ0sY" title="YouTube video player" width="560"></iframe>

Documenting Multiple Liferay Versions

Liferay documentation defaults to the latest version. A single article covers all minor versions of a feature within one major version. Sometimes you must document an older version alongside the current one:

When Liferay modifies the user interface for a feature
When Liferay deprecates or removes a feature, but users still use the old version
When Liferay adds new functionality to an already existing feature

In these cases, you must support more than one version of the software in the documentation. Here are some ways to do that:

Do not create a new article to discuss the changes in a new software minor version. Keep all the content for the same software major version in the same article.
Place the newest information at the top of the article and the oldest information at the bottom.
Evaluate the impact of the changes in the existing document:
- For minor changes, use version badges to let readers know which version the content applies to. If the change requires a header, place the note right after the header.
- For major changes, use a dedicated H2 section to discuss the changes and place a note-type admonition at the beginning of the topic cross-linking the H2.

Heading Hierarchy

Use headings to create a logical hierarchy that helps readers scan and navigate the article. The levels correspond to these purposes:

H1: The article title. There is exactly one H1 per article. The writer writes it as the first heading in the document and must ensure it matches the article’s title metadata.
H2: Major sections within an article. Most articles consist of H2 sections only.
H3: Subsections when a major section contains two or more distinct sub-topics that each require their own heading.
H4: Use sparingly. Only when an H3 section itself contains distinct sub-categories that cannot be condensed.

Avoid H5 and H6 entirely. If you find yourself reaching for them, the article needs restructuring or the content belongs in a separate article.

Do not skip levels (for example, jumping from H2 to H4). Screen readers and automated tools depend on a consistent hierarchy.

Document Type Format Templates

Each document type follows a specific structure. Use these outlines as a starting point.

Introduction

An introduction sits at the top of a section and orients the reader.

# [Topic Name]  (never "Introduction to [Topic]")

[Opening paragraph: what the feature is and the primary value it provides — 2–4 sentences]

[Use cases: what problems it solves and when to use it]

[Prerequisites or required setup, if any]

## [Child Article 1 Title]

[One-sentence description of what this child article covers]

## [Child Article 2 Title]

[One-sentence description]

Concept

A concept article explains a topic in depth, either before or after a feature article.

# [Concept Name]

[Opening paragraph: what the concept is — 1–3 sentences]

## [Aspect or Sub-topic]

[Explanation]

## [Related Feature or Next Step]

[Link to the relevant feature article]

Feature

A feature article describes a single feature and how to use it. This is the most common document type. Include reference content (configuration options, field descriptions) at the end of the feature article unless it is large enough to warrant its own article.

# [Feature Name or Task Name]

[Opening paragraph: what the feature does, its business value, and when to use it — 1–3 sentences]

[Prerequisites section, if non-obvious setup is required]

1. [Step one]

1. [Step two]

1. [Step three]

## [Additional Options or Configuration Section]

[Description and steps for secondary workflows]

## [Feature Name] Reference

[Include inline here when reference content is small; otherwise split into a separate reference article and link to it]

Reference

A reference article documents configurations, settings, or options for a feature. Create a separate reference article when the reference content is too large to fit comfortably at the end of the feature article. Link to it from the feature article.

# [Feature Name] Reference

[One-sentence description of what is covered — e.g., "This reference describes all configuration options for the Foo widget."]

## [Configuration Section or Setting Group]

| Field | Description |
| :--- | :--- |
| [Field Name] | [What it does and any constraints] |
| [Field Name] | [What it does and any constraints] |

## [Another Configuration Section]

[Table or definition list as appropriate]