Tutorials

This page provides guidelines for writing effective tutorials in the Elastic docs.

A tutorial is a comprehensive, hands-on learning experience that guides users through completing a meaningful task from start to finish. You can think of a tutorial as a chain of related how-to guides, with additional explanatory context to help users learn as they work.

Ideally, users can complete a tutorial without needing to jump to other guides. Of course, this is more of an art than a science, and it's important to balance the need for background context with overall readability. If you find yourself needing to write a lot of background context, consider writing multiple, more focused tutorials.

Tutorials include three essential components:

• Clear learning objectives that describe what users will be able to do by the end
• Prerequisites and setup needed before starting
• A sequence of instructional steps that build on each other to accomplish a larger goal

When you create tutorials, follow these best practices:

• Focus on learning outcomes: State what users will be able to do and the value they'll gain. Learning objectives should be clear, achievable, and relevant to real-world tasks.
• Choose your tutorial approach: Tutorials can be feature-focused or scenario-driven. Both are valid. Refer to examples for inspiration.
  • Feature-focused: Explore features or functionality (useful for deep dives into specific feature sets)
  • Scenario-driven: Work through a real-world use case (useful for demonstrating end-to-end solutions)
• Gradually introduce complexity: Start with simple concepts and use progressive disclosure. Each step should build on the previous steps.
• Provide context when needed: Unlike how-to guides, tutorials benefit from explanations of why something works or why a particular approach is recommended. That said, it's important to keep the tutorial as concise and focused as possible. Err on the side of brevity.
• Use realistic examples: Create examples that mirror real-world scenarios users will meet where possible.
• Guide the learner: Assume users are new to the feature or workflow. Provide encouragement and explain what they're accomplishing at key milestones.
• Include checkpoints: Add verification steps throughout so users can confirm they're on the right track before continuing.
• Test your tutorial: Authors and reviewers should complete the entire tutorial from scratch to identify gaps, errors, or unclear instructions.
  Tip

  Have someone unfamiliar with the feature try your tutorial. They'll find every gap and unclear step!

To help users successfully complete the learning experience, tutorials use a consistent structure. A predictable format helps users understand what they'll learn, what's required, and what they'll achieve.

The following elements are required in tutorials:

• A consistent filename: Use descriptive patterns like *-tutorial.md.
  • For example: ingest-pipeline-tutorial.md
• Appropriate frontmatter:
  • applies_to: Tags for versioning/availability info per the cumulative docs guidelines
  • description: A brief summary of what users will learn
  • product: The relevant Elastic product(s) used in the tutorial

• A clear title: A descriptive title that indicates what users will learn or accomplish
  • For example, "Build an ingest pipeline with processors"
• An overview: Explain what the tutorial teaches, who it's for, and what users will be able to do by the end. Include:
  • A brief description of what users will learn
  • The intended audience and their expected skill level
  • Learning objectives as a bulleted list
• A before you begin section: List all prerequisites including:
  • Required prior knowledge or skills
  • Software, hardware, or access requirements
  • Data sets or environments to set up
  • Estimated time to complete (optional but helpful)
• Instructional steps: Organize the tutorial into logical sections, each with a descriptive heading. Use numbered steps that begin with imperative verbs.
  Tip

  Use the stepper component for visual flow, or add subheadings to break complex steps into subsections.

• Checkpoints and results: After significant steps, show users what they should see or what state their system should be in.
• Code annotations: Explain important lines within code blocks to help users understand the code. Annotations can help reduce the need for extra text in the body of the tutorial, keeping the tutorial concise and focused. This makes it easier for a reader to simply run through the steps in a hurry.
• Next steps: Suggest follow-up tutorials, related features to explore, or ways to expand on what they built.
• Related pages: Links to related documentation such as conceptual topics, reference material, how-to guides, or troubleshooting resources.

Include the following when they add value:

• Screenshots: Add visual aids for UI-based steps when they improve clarity. Use screenshots sparingly as they require maintenance.
• Explanatory callouts: Use admonitions to provide extra context, troubleshooting tips, or explanations without interrupting the main flow.
• Time estimates: Indicate how long each major section or the overall tutorial takes to complete.
• A summary: Recap what users learned and accomplished in the tutorial. Reinforce the key learning objectives.

To get started writing your tutorial, use the template.

Here are some examples of well-structured tutorials in the Elastic documentation:

• Tutorial: Threat hunting with ES|QL: A scenario-driven tutorial that teaches ES|QL through a realistic cybersecurity scenario, with extensive code annotations.
• ES|QL for search tutorial: A feature-focused tutorial that systematically teaches search concepts using ES|QL, from basic text matching to AI-powered semantic search, with subsections breaking down complex topics.