Liferay High-Level Style

There are four types of documentation:

1. Introduction: Placed hierarchically at the top of a section, the introduction is a high level explainer that summarizes how the feature can help the reader. It focuses on use cases that solve real-world problems. It also tells readers how the rest of the section enables them to use the feature optimally.

2. Concepts: When a topic requires extensive explanation outside the individual features or the introduction, a concept document fills the gap. This can be placed either before a feature document that shows how the feature works, or more often, after a feature is described, to show all the options available in the feature. An example of the former is Collection Pages; an example of the latter is a description of all the available Workflow Nodes.

3. Feature: The foundation of all documentation covers each feature and how it works. Keeping paragraphs and explanations to a minimum, feature documentation describes—using numbered steps—how readers can use all of Liferay’s features. Feature documentation can be user-focused or developer-focused. Liferay’s documentation should always be feature-complete. Feature articles may include reference content (configuration options, field descriptions) inline when that content is small.

4. Reference: Documents configurations, settings, and options 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.

Documentation Voice

We expend much effort to unify the voice of Liferay’s documentation. To make many writers sound like one, Liferay’s technical writers follow a set of standards and an editorial process that helps ensure that readers encounter the same writing style per article regardless of which writer wrote it. The high level characteristics of this voice are friendly and casual. Beyond that, we keep to the rules listed in chapters one and two of The Elements of Style with a particular emphasis on the rule titled Omit Needless Words.

Friendly

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

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"

With that said, we avoid documenting other products. For example, in clustering articles, we document what’s necessary for configuring Liferay to work in a clustered environment, and we avoid documenting app server configurations beyond our own Docker containers.

Casual

Documentation is written in a casual style to make it easy to understand for those for whom English is not a first language. We avoid formality and unnecessarily large words. Contraction use is encouraged to reduce word count and help make the text flow.

Steps Rather Than Paragraphs

Whenever possible, break procedural matters into numbered steps, rather than describing them in paragraphs. Information can be buried inside paragraphs and is much easier to find if it appears as part of a numbered list. Additionally, if customers have trouble following the steps, it is helpful to Liferay Support if they can provide the exact step number where the trouble began.

Omit Needless Words

William Strunk’s famous rule, Omit Needless Words, is our mantra. Liferay Technical Writers should study chapters one and two of Elements of Style and follow all the rules, but keep this one most of all in mind. The Liferay Phraseology guide has a list of oft-used phrases that can be shortened or eliminated to tighten up your writing.

Obviously, Strunk and White’s rules were not directed toward technical writers specifically, but to all writers, who would do well to learn from their experience when writing in any style. Liferay’s specific standards for technical documentation (below) are based on the foundation of Elements of Style.