Documentation Style

This article covers rules that apply only to product documentation: the six documentation types and their templates, how to handle multiple Liferay versions, the badges that mark commercial, support, or version status, and documentation-specific phraseology. For shared rules, see Core Style and Formatting. For courses, see Course Style.

Documentation Types

There are six types of documentation, each with a specific role:

Introduction: Sits hierarchically at the top of a section and is a high-level explainer that summarizes how a feature helps the reader. It focuses on use cases that solve real-world problems and tells readers how the rest of the section enables them to use the feature optimally.
Concept: When a topic requires extensive explanation outside an individual feature or its introduction, a concept article fills the gap. Concept articles can come before a feature article (to establish prerequisite ideas) or after it (to describe all the options available within the feature). An example of the former is Collection Pages; an example of the latter is the description of all available Workflow Nodes.
Feature: The foundation of documentation. Feature articles cover individual features, keeping paragraphs and explanations to a minimum and using numbered steps to describe how readers use the feature. Feature articles can be user-focused or developer-focused. Feature documentation should be feature-complete; reference content (configuration options, field descriptions) can be included inline when small.
Reference: Documents configurations, settings, options, APIs, and other lookup-oriented information for a feature in detail. Reference content belongs in its own article when it is too large to include at the end of a feature article. Reference articles are always linked from the feature article they support.
Example: Complements the foundational feature documentation. When a feature is simple enough to understand fully from the feature article and reference article (if included), an example article is not needed and adds unnecessary bloat. However, when the feature is important strategically, can be used in many ways, or the user experience is not intuitive, examples can help crystallize the value of the feature and bootstrap customer implementations. Example articles should include multiple concrete step-by-step example use cases that are built and tested. See Custom Filter Examples and Custom Element Examples (for Search Blueprints).
Tutorial: Documents extension points, API endpoints, and complex strategic features (for example, Objects and Search Blueprints) by demonstrating how to accomplish something. Deployable or runnable code supporting the tutorial lives in an article-name/resources/liferay-a1b2.zip folder (a1b2 is a four-character letter-number-letter-number sequence that must be unique in the repository).

Document Type Templates

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

Introduction Template

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 Template

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 Template

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 Template

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 — for example, "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]

Example Template

An example article presents concrete, built-and-tested use cases that show the feature in action. Each use case leads with its configuration or code, followed by an explanation; add steps and screenshots only when a use case requires hands-on setup.

# [Feature Name] Examples

[What these examples demonstrate and who they help.]

- [Use Case 1 Name](#use-case-1-name)
- [Use Case 2 Name](#use-case-2-name)

See [Using the Feature](./using-the-feature.md) for a full explanation.

## [Use Case 1 Name]

[What this example accomplishes and when to use it.]

[The concrete configuration or code — field/value settings or a JSON or Java snippet.]

[Prose explaining what it does and why.]

## [Use Case 2 Name]

[Description and configuration. Add numbered steps with **Checkpoint:** callouts and screenshots only when the example requires hands-on setup.]

## Related Content

- [Link to the feature article]
- [Links to related reference or concept articles]

Tutorial Template

A tutorial demonstrates how to accomplish something with an extension point, API, or complex feature: deploy a working example, then explain how it works. Supporting code lives in the article’s resources/liferay-a1b2.zip folder and is pulled into the article with literalinclude.

# [Task or Extension Point Name]

[What you build and the interface, extension point, or API it demonstrates. Link to the source interface/API and the related feature article.]

## Deploy an Example [Thing]

[Include the run-liferay-dxp environment snippet here with an `{include}` directive. The `_snippets` folder lives under `dxp/`, so point at it with a relative path from the article, for example `../../../../dxp/latest/en/_snippets/run-liferay-dxp.md`.]

1. Download and unzip the example project.

   ```bash
   curl https://resources.learn.liferay.com/[path]/liferay-a1b2.zip -O

   unzip liferay-a1b2.zip
   ```

1. Build and deploy the example.

   ```bash
   ./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
   ```

1. Confirm the deployment in the Docker container console.

   ```bash
   STARTED com.acme.a1b2.impl_1.0.0
   ```

1. [Exercise the feature in the UI, with screenshots and checkpoints.]

## How the Example Works

### [First Code Element]

[Pull the relevant source from the example project with a `{literalinclude}` directive, for example `./<article-name>/resources/liferay-a1b2.zip/<path>.java` with `:language:` and `:lines:` options.]

[Prose explaining this portion of the code.]

## Conclusion

Congratulations! You now know [what the reader accomplished].

Documenting Multiple Liferay Versions

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 readers still use the older version.
When Liferay adds new functionality to an already-existing feature.

In these cases, support more than one version in the same article. Some ways to do that:

Do not create a new article to discuss changes in a new minor version. Keep all content for the same major version in the same article.
Place the newest information at the top of the article and the oldest at the bottom.
Evaluate the impact of the changes:
- For minor changes, use version badges to let readers know which version the content applies to. If the change requires a header, place the badge 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 article cross-linking the H2.

Badges

There are four documentation badges: subscription, unsupported, version, and feature flag. Use them to mark articles or sections as appropriate.

Subscription

Mark a feature available only with a Liferay DXP Enterprise Subscription, not in the Free Tier:

<span class="bdg bdg-primary">Subscription</span>

Unsupported

Mark a feature that exists but is not supported:

<span class="bdg bdg-warning">Unsupported</span>

Version

Mark a feature that appears in particular versions of the product:

<span class="bdg bdg-secondary">7.4 U15+ and GA15+</span>

Feature Flag

Mark a feature that is gated behind a feature flag with a link badge that names the flag stage and links to the matching section of the Feature Flags reference. Use the stage that applies:

<span class="bdg bdg-link-primary">[Beta Feature](../../security-and-administration/administration/configuring-liferay/feature-flags.md#beta-feature-flags)</span>

<span class="bdg bdg-link-primary">[Dev Feature](../../security-and-administration/administration/configuring-liferay/feature-flags.md#dev-feature-flags)</span>

<span class="bdg bdg-link-primary">[Release Feature](../../security-and-administration/administration/configuring-liferay/feature-flags.md#release-feature-flags)</span>

The relative path to feature-flags.md depends on the article’s depth in the tree; count the ../ segments from the current article. When a feature graduates to General Availability, remove the badge.

For more on badges, see the Sphinx Design documentation.

Phraseology

Documentation-specific phraseology. For the shared phraseology rules that apply to all content, see Core Style.

“Designed To”

The phrase is designed to is usually unnecessary. State what the software, process, or component does directly. The same applies to its kin — is intended to, is meant to, is built to, and is tailored to.

Bad: The system is designed to support custom workflows.

Good: The system supports custom workflows.

Bad: These processes are designed to affect only obsolete data.

Good: These processes affect only obsolete data.