Course Style

This article covers rules that apply only to course content: the elements that distinguish a course from a feature article, the course and module structure, naming conventions, lesson and exercise patterns, learning objectives, assessments, courses-specific visual conventions, and course-specific phraseology. For shared rules, see Core Style and Formatting. For product documentation, see Documentation Style.

What Distinguishes Course Content

Course content differs from feature documentation in three ways. Every course must incorporate and focus on these three elements; if a course is missing any of them, it has slipped into being feature documentation.

Best Practices: Provide clear, opinionated guidance on selecting and using Liferay features. Lessons should offer recommendations, highlight best practices, and caution against common pitfalls.
Story: Organize lessons and exercises around a realistic use case. Lessons apply Liferay features and best practices to the use case; exercises guide learners through implementing something for it.
Business Value: Module lessons and exercises should demonstrate the practical benefits of Liferay features, not merely claim them. Stating business value once or twice is fine; after that, the content has to prove it.

The Clarity Vision Solutions Case Study

Course content uses Clarity Vision Solutions as its case study. Clarity is a fictional company that gives every course a consistent narrative spine: the same characters, the same business problems, the same solution architecture, applied to whichever Liferay capability the course covers.

Use Clarity throughout the course wherever a real-world example is needed:

The introduction always transitions into the Clarity case study at the end.
Lessons connect the material to Clarity’s business goals and challenges.
Exercises guide learners through implementing solutions for Clarity, not for an abstract user.
Knowledge Checks and Badge Tests focus on concepts; Clarity-specific scenarios appear in lesson and exercise prose, not in assessments.

Course Structure

Every course has the same top-level structure:

Introduction: Welcomes the learner, states the course’s purpose, identifies the audience (developer, business user, administrator, etc.), notes prerequisites, and outlines the learning objectives.
Getting Started with Clarity: Introduces the case study — Clarity’s story, its goals, its challenges, and the critical success factors the course will address.
Course Environment Setup: Step-by-step instructions for installing software, configuring settings, and accessing course-specific resources. There are two versions: one for business users and one for developers. Use the version that matches the course’s audience. Omit this article if the course does not require a GitHub repository.
Modules: Organized learning content. See Module Structure. Foundations courses do not use module divisions.
Conclusion: Summarizes the course’s key takeaways and links to related Liferay Learn resources.
Badge Test: A final test that evaluates retention of course concepts and best practices.

Module Structure

Course modules are the primary building blocks of a course. Each is dedicated to a specific use case or technical topic — never to a single product feature. Every module has this structure:

Overview: A concise introduction that establishes the topic and lists the module’s learning objectives.
Lessons: Connect material to the Clarity story, highlight the business value of Liferay features, and promote best practices. See Lessons for the three lesson patterns.
Demos: Short videos that demonstrate key concepts and best practices. (For now, demos are for in-person training; in the future they will appear as videos in online courses.)
Exercises: Guided, hands-on activities where learners apply what they have learned. See Exercises.
Knowledge Check: A five-question quiz that reinforces the module’s essential takeaways. See Assessments.

Organizing Principles

The principle Organize by user goal, not by feature is in Core Style because it applies to documentation as well, but it is especially load-bearing for courses. The same applies to Happy path first, also in core. The principles below are courses-specific.

Integrate Common Considerations

Some topics are integral to best practices and should be woven directly into lessons rather than treated as separate modules:

Troubleshooting: Equip learners with the knowledge to identify and resolve common issues related to the module’s topic.
Performance: Raise performance considerations throughout lessons; guide learners on how to optimize for speed and efficiency.
Testing: Where appropriate, promote testing as essential and provide guidance on how to perform tests for the topic at hand.
Security: Integrate security considerations into every module so learners understand how to build secure solutions.

Follow Natural Divisions

Effective module organization follows the natural divisions within a use case or technical topic:

Identify distinct parts: Break the use case down into key components or stages.
Recognize sequential dependence: Identify what must come first conceptually (what the learner needs to understand) and practically (what implementation steps must be completed before others).

When this works, learners grasp the overall process while mastering individual steps.

Naming Conventions

Consistent naming helps learners navigate the course hierarchy. Titles distinguish broad topics (Modules) from specific actions or concepts (Lessons and Exercises).

Modules

Module titles represent an overarching topic, business need, or capability. They are noun phrases — never actions, gerunds, or Liferay feature names.

Format: [Noun Phrase / Topic]
Examples: Foundations of Content Management, Site Styling, Process Automation, Data Modeling.

Lessons

Lesson titles fall into three patterns. Each begins with a gerund and focuses on a specific task.

Understanding lessons explore concepts and principles fundamental to the module’s topic. They always begin with Understanding (e.g., Understanding Liferay Objects).
Strategic lessons explore strategic considerations and architectural decisions for the module’s topic. They always begin with Determining (e.g., Determining an Effective Content Management Strategy).
Use case lessons focus on a specific task or use case within the module’s topic. They use a descriptive gerund (e.g., Structuring Page Layouts).

Exercises

Exercise articles include hands-on activities where learners apply lesson concepts to Clarity. They begin with a gerund and always include Clarity in the title to reinforce the storytelling spine.

Format: [Gerund] + Clarity’s + [Object] or [Gerund] + [Object] + for Clarity
Examples: Setting Up Clarity’s Warehouses, Configuring Promotions for Clarity.

Naming Examples

Component	Bad	Good
Module	Designing Sites / Designing for Accessibility	Site Design / Accessibility
Lesson (Understanding)	What are Fragments	Understanding Page Elements / Understanding Site Styling
Lesson (Strategic)	Design Strategy	Determining a Site Design Strategy
Lesson (Use Case)	Using Layout Fragments	Structuring Page Layouts
Exercise	Creating a Custom Theme	Styling Clarity’s Website

Course-Level Content

Course Introductions

A course introduction engages the reader and answers four questions:

Why should you take this course? Spark interest by communicating the relevance of the topic to a business outcome.
Who is this course for? Clearly identify the target audience (developer, business user, administrator).
What prerequisites are there? List required prior courses, knowledge, or skills.
What will you learn? Present the learning objectives.

Always conclude the introduction by transitioning into the Clarity case study. See this example.

Getting Started with Clarity

The Getting Started with Clarity article introduces the case study. It includes:

A brief introduction of Clarity Vision Solutions.
A statement of the problems Clarity is trying to solve.
A list of critical success factors with brief descriptions of the Liferay features that address them.
A description of the course’s solution that lessons reference and exercises implement.

Keep this content brief and focused. See this example.

Module Introductions

Module introductions briefly identify the module’s topic and bridge what has been learned to the new challenges ahead. The structure is two paragraphs and a list of learning objectives:

Paragraph 1: Express the business value of the module’s topic, briefly note the key requirements or challenges, and conclude with how Liferay provides the tools to meet them.
Module Banner: Insert the module banner image between the paragraphs.
Paragraph 2: Briefly recap what the learner has covered so far (“So far you’ve…”) and state what they will cover in the current module (“In this module, you’ll…”).
Learning Objectives: A list of learning objectives scoped to the module.
Concluding Transition: Direct the learner to the first lesson’s topic (“You’ll begin with exploring…”).

See this example.

Learning Objectives

Provide learning objectives at the start of each course and module. Objectives clearly identify the knowledge and skills students should acquire. Follow this pattern:

By the end of this course, you will have the knowledge and skills to

[INSERT LEARNING OBJECTIVES]

Ensure objectives are specific, measurable, achievable, relevant, and time-bound (per SMART guidelines). See this example.

Lessons

Lessons provide the conceptual foundation. They explain the mechanics and logic of Liferay features while highlighting industry best practices and using Clarity to demonstrate real-world business value. Lessons let learners understand the why behind their actions before moving into hands-on work.

Understanding Lessons

These lessons introduce foundational concepts and capabilities — what a feature is, its architecture, and its role within Liferay. Examples: Understanding Liferay’s Commerce Capabilities, Understanding Orders and Order Types, Understanding Promotions and Discounts.

Use Case Lessons

These lessons focus on strategic, real-world implementations — how to combine features to solve specific business challenges. Examples: Determining a Commerce Implementation Strategy, Managing Commerce Users, Building Storefronts.

Lesson Structure

Lesson Introduction: One paragraph maximum. Include four key elements: a clear business goal related to the topic (e.g., empowering sales reps to serve customers), relevant requirements (a way to structure sales-rep teams), the main Liferay tools that address the goal (Organizations), and the benefits of using those tools (streamlining access control for security and scalability). Follow the introductory paragraph with a separate standalone sentence stating the focus of the lesson (“In this lesson, you’ll…”).
Main Body: [WIP — to be drafted as the style matures.]
Clarity Application: [WIP.]
Conclusion: [WIP.]

Exercises

In Exercise articles, learners apply the concepts from the module’s lessons. Each exercise article can include one or more individual exercises. The goal of every exercise is for learners to follow best practices while solving a specific business problem for Clarity.

Article Structure

General Introduction: One paragraph maximum. The first sentence states the strategic importance of the topic. The next sentence or two connect the topic to the Clarity case study. The last sentence states the overall goal of the exercises (“In these exercises, you’ll…”).
Individual Exercises: Each is its own H2 section, titled Exercise: [Title].
- Exercise Introduction: Two or three sentences. Always conclude with a meta comment about the specific exercise (“Here you’ll [specific task] as [persona].”).
- Step-by-Step Instructions: For the first exercise, specify the persona and provide credentials. Use direct, imperative commands (“Click,” “Enter,” “Verify”). When first explaining a process, be explicit and detailed; for repeated activities, condense. After a key step, include a brief, non-intrusive sentence or two that explains the purpose or result (“This ensures…”). Where appropriate, ask learners to verify the result of their action.
- Exercise Conclusion: Note the learner’s accomplishment (“Great! You’ve…”) and gesture toward the next exercise (“Now you can…”) without being too specific.
General Conclusion: Around three sentences. Restate the strategic importance of the topic, briefly summarize what the learner accomplished for Clarity, note any keys to success, and end with the standard Next, you’ll… transition sentence.

Exercise Principles

Maintain focus: Each exercise accomplishes one primary goal.
The happy path: The first time a learner performs a new task, the exercise must guide them through the simplest, most recommended process. (See Happy Path First in core.)
Purpose-driven actions: Every click, command, and configuration must be a logical and necessary step toward solving the specific business problem defined for Clarity. There should be no extraneous steps; if an action does not directly contribute to the goal, remove it.
Precision: An exercise is an instruction manual. Its language must be precise and avoid ambiguity (no equivocation, no hedging).

Article Transitions

Article introductions and conclusions link the course together.

Introductions should engage the reader and establish context. Assume that learners stepped away between articles, but do not recap everything. Mention Clarity. Material should flow.

Conclusions should be two to five sentences. The first sentences recap the main points of the article (a brief TL;DR); the last sentence forecasts where the learner is going next. Use this pattern:

Next, you’ll [next article’s topic].

When transitioning to a Knowledge Check:

Next, you’ll review what you’ve learned before moving on to the next module.

When transitioning to a Knowledge Check before a Conclusion:

Next, you’ll review what you’ve learned before concluding the course.

Course Conclusions

Every course has a Conclusion article before the final Badge Test. Use this template:

Congratulations! You’ve successfully completed the [Course Name] course.

[Brief paragraph about the course’s topic and key takeaways.]

This course has equipped you with the knowledge and skills to:

[List the course’s learning objectives.]

Related Information

To continue learning about [Course Topic], consider taking these courses:

[Link to other courses in the learning path.]

Next, complete the course test to earn your badge!

Assessments

Assessments validate that learners have not only consumed the content but have also retained and mastered it. There are three tiers.

Comparison

Feature	Knowledge Checks	Badge Tests	Certification Exams
Primary purpose	Review key concepts and validate basic comprehension of module concepts.	Ensure retention and comprehension of key course concepts.	Certify mastery of role-based knowledge and skills (Content Manager, Liferay Application Developer, etc.).
Platform	Learn LMS	Learn LMS	Webassessor
Question count	5	20+	50+ (drawn from a 250+ pool)
Difficulty	Low–Moderate	Moderate	Moderate–High
Results	Not recorded; does not block progress	Recorded; required for the course badge	Recorded; confers official Liferay Certification
Retries	Unlimited	Unlimited	Limited

Knowledge Checks

Knowledge Checks are a low-stakes review tool at the end of a course module. They validate that learners understand the module before moving on. Each Knowledge Check has exactly five questions focused on the module’s essential takeaways.

Drafting principles:

Direct and clear: Unambiguous; avoid trick constructions.
Lesson-based: All answers are explicitly found within the module’s lessons.
Concept-focused: Focus on key definitions, distinctions, and best practices. Avoid Clarity-specific scenarios.
Consistent terminology: Reuse the exact terminology and language from the lessons to assist retention.

Knowledge Checks are created and managed in the Liferay Learn LMS. See Creating Knowledge Checks.

Badge Tests

Badge Tests validate that the learner has retained the most critical takeaways from the entire course. They are comprehensive and required for earning the course’s badge. Each badge test must include 20 or more questions.

Badge Test questions share most principles with Knowledge Checks, with these exceptions:

Comprehensive coverage: Distribute questions across all course modules.
Prioritization: Prioritize big-picture concepts and strategic best practices that were essential to completing the course.
Moderate difficulty: Ensure the correct answer is not too obvious. Go beyond simple definitions — include questions that require identifying the right tool or configuration for a specific scenario.

Badge Tests are created and managed in the Liferay Learn LMS. See Creating Badge Tests.

Certification Exams

Certification Exams are high-stakes assessments that certify professional mastery of role-based knowledge and skills. They are created, managed, and administered in Webassessor, where each exam is dynamically generated by drawing 50 or more questions from a larger pool of 250+.

Drafting principles:

Application-centric: Prioritize use-case questions that require applying knowledge to a specific scenario.
Search-proof: Minimize simple, definition-based questions that are easy to look up.
Narrative neutral: Do not reference Clarity. Use generic, professional scenarios that apply broadly.

Question Types

Four primary question types evaluate different levels of understanding:

Definition: Tests basic comprehension by asking the learner to identify the meaning of a Liferay term or feature.
Categories: Asks the learner to group features or concepts based on function or relationship (for example, distinguishing types of Client Extensions).
Best Practices: Focuses on the principles and standards governing Liferay implementation. Emphasizes recommended architectural or procedural rules over mere functional possibility.
Use Case / Application: Presents a business or technical requirement within a scenario; the learner analyzes and selects the correct implementation. Highest tier; primary focus of certification.

Use this table to determine which question types belong in which assessments:

Question Type	Knowledge Checks	Badge Tests	Certification Exams
Definition	Primary	Secondary	Tertiary
Categories	Primary	Primary	Secondary
Best Practices	Primary	Primary	Primary
Use Case / Application	Avoid	Avoid	Primary

Managing Question Difficulty

The true difficulty of a question is determined by the plausibility of its options. A question is only as challenging as its most convincing distractor (incorrect answer).

Knowledge Checks: Distractors are clearly distinct from the correct answer. Anyone who has read the lesson should identify the correct response with confidence.
Badge Tests: More nuanced distractors that represent common misunderstandings or similar (but incorrect) Liferay features. The learner must distinguish between related concepts, not just recognize a familiar term.
Certification Exams: Highly plausible distractors that represent functional but non-optimal solutions. The correct answer is the only one that adheres strictly to Liferay best practices for the given scenario.

Regardless of tier, avoid throwaway answers that are obviously absurd.

Visuals

For shared image, alt-text, diagram, and screenshot guidance, see Formatting. The conventions below apply specifically to courses.

Diagrams and Decorative Designs

The Design team produces course-specific graphics: diagrams, course banners, module banners, and badges. Diagrams represent abstract concepts, high-level architectures, or backend processes. Decorative elements (banners, badges) provide visual identity and milestone markers. See the Brand portal for existing course diagrams.

Requesting Designs

Jira automation automatically creates DESIGN epics and standard banner/badge tickets for new courses. For course maintenance, create DESIGN epics manually.

Initiate early: Open DESIGN tickets as soon as you become aware of design needs.
New course epics: Course: [Course Name]
Maintenance epics: 2026 Q1 Graphic Design Updates for [Course Name]
Individual requests: [Design Type]: [Brief Description] (for example, Diagram: Team-Based Development).
Align due dates: Ensure DESIGN ticket due dates align with their corresponding ENBT ticket due dates.
Updates to existing designs: Open a new ticket in the course’s DESIGN epic and reference the original design ticket in the description.

For more information, see the internal Designs process.

Screenshots

Use screenshots when:

First introducing key UI elements or applications.
Learners are completing complex or confusing exercise steps.
Learners reach a key exercise checkpoint.
Learners complete an exercise and need to verify success.

Screenshots help learners verify they are on the right track before moving forward. Use them judiciously; avoid obscuring the surrounding text and consider the maintenance overhead they create.

When you need to show multiple UIs for a single application or visually link a multi-step process to its final result, use a collage of screenshots.

Markup

Use markup to draw the learner’s eye to specific UI elements:

Color: #FFC10C for all screenshot markup.
Boxes: Focus the reader’s attention on specific UI elements.
Arrows: Visualize relationships or sequences between elements.
Numbers: Used for UI reference images where multiple elements are identified. Pair numbers with explanations in the surrounding lesson or exercise text.

Framing

Provide context: Avoid cropping so tightly that learners lose orientation.
Maintain focus: Eliminate noise. Avoid full-screen or indiscriminate browser shots that include unrelated UI regions.
Direct the eye: Use the standardized markup color (#FFC10C) to direct attention to the specific UI elements being discussed.

UI Icons

Use a standardized set of UI icons rather than manual crops whenever possible.

Standard source: Export UI icons from the Lexicon Icons Figma as PNGs.
Exceptions: When the Figma does not include the coloration you need, use a high-quality screenshot of the icon.
Asset sharing: Everyone uses the same icon images for consistency.

Phraseology

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

“Designed To”

State directly what a feature does (“Objects stores custom data,” not “Objects is designed to store custom data”). When a lesson’s goal is to teach why a feature exists, you may use purpose-framing — is designed to, is meant to, is built to — because the purpose itself is the teaching point. Default to the direct form; reserve purpose-framing for those moments.