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:
Documentation is Comprehensive: it shows everything you need to know about the software.
Documentation is Concise: it gets to the point and avoids fluff.
Documentation is Cohesive: individual documentation relates to an overall message.
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.
Solutions and Courses complement feature and conceptual documentation by describing full implementations of Liferay software. Solutions documentation leads the reader through creating specific applications of Liferay, such as the Raylife insurance application or the Minium commerce implementation. Courses lead the reader through the comprehensive building blocks of implementing Liferay for a production site, from provisioning the server all the way to analyzing site traffic.
In this way, Liferay is able to satisfy the learning needs of all who want to use or evaluate Liferay for their needs.
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 (feature, conceptual, solutions, and courses) 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’s Ask application.