[Contribution initiative] Add tutorial content type

contribute-docs/content-types/_snippets/how-to-tutorial-disambiguation-note.md

@@ -0,0 +1,10 @@
+:::{note}
+Tutorials differ from how-to guides in scope and purpose:
+
+- **[How-to guides](/contribute-docs/content-types/how-tos.md)** are focused recipes for a single, discrete task with minimal explanation
+- **[Tutorials](/contribute-docs/content-types/tutorials.md)** chain multiple tasks together with explanatory context, teaching users broader skills and workflows
+
+::::{tip}
+If your content has more than 10 overall steps, teaches a broader skill, or requires significant explanation between steps, use a tutorial.
+::::
+:::

contribute-docs/content-types/_snippets/templates/tutorial-template.md

@@ -0,0 +1,159 @@
+---
+description: "A brief summary of what users will learn in this tutorial, fit for search results and tooltips."
+applies_to:
+  stack:
+  serverless:
+type: tutorial
+product:
+---
+
+<!-- Copy and paste this template to get started writing your tutorial, deleting the instructions and comments from your final page.
+
+For complete guidance, refer to [the tutorial guide](https://www.elastic.co/docs/contribute-docs/content-types/tutorials).
+
+-->
+
+# [Descriptive title indicating what users will learn]
+<!-- REQUIRED
+
+A clear, descriptive title that indicates what users will learn or accomplish.
+
+Examples:
+- Build an ingest pipeline with processors
+- Work with datetimes in ES|QL
+- Tutorial: Threat hunting with ES|QL
+-->
+
+## Overview
+<!-- REQUIRED
+
+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
+-->
+
+In this tutorial, you'll learn how to [brief description of the main task]. This tutorial is intended for [target audience]. It assumes you have basic knowledge of:
+
+- [Prerequisite concept 1]
+- [Prerequisite concept 2]
+
+By the end of this tutorial, you'll be able to:
+
+- [Learning objective 1 — clear, achievable, and relevant to real-world tasks]
+- [Learning objective 2]
+- [Learning objective 3]
+
+## Before you begin
+<!-- REQUIRED
+
+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)
+-->
+
+You'll need:
+
+- [Software or access requirement 1]
+- [Software or access requirement 2]
+- [Data or configuration requirement]
+
+<!-- OPTIONAL: Estimated time -->
+Estimated time: [X minutes/hours]
+
+## Step 0: [Setup or data preparation]
+<!-- OPTIONAL BUT COMMON
+
+If the tutorial requires setup, sample data, or initial configuration, include it as Step 0. This keeps the tutorial self-contained.
+-->
+
+[Instructions for setting up the environment or adding sample data]
+
+```language
+[Setup code or commands] <1>
+```
+
+1. [Code annotation explaining what this does]
+
+## Step 1: [First instructional task]
+<!-- REQUIRED
+
+Organize the tutorial into logical sections, each with a descriptive heading. Use numbered steps that begin with imperative verbs.
+
+TIP: Use ### subsections to break complex steps into manageable pieces.
+-->
+
+[Brief introduction to what this step accomplishes and why it matters]
+
+### [Subsection for complex steps - optional]
+
+[Explanatory context about why this approach is recommended]
+
+```language
+[Code example] <1> <2>
+```
+
+1. [Code annotation explaining important lines]
+2. [Additional annotation for clarity]
+
+<!-- REQUIRED: Include checkpoints after significant steps -->
+**Result:** [Describe what users should see or what state their system should be in]
+
+## Step 2: [Second instructional task]
+<!-- Build on previous steps with progressive complexity -->
+
+[Introduction to this step, building on what was learned in Step 1]
+
+```language
+[Code example showing the next concept] <1>
+```
+
+1. [Code annotation]
+
+**Result:** [Expected output or system state]
+
+## Step 3: [Additional steps as needed]
+
+[Continue building complexity progressively]
+
+## Summary
+<!-- OPTIONAL
+
+Only include if it adds value beyond repeating the overview. Recap what users learned and accomplished.
+-->
+
+In this tutorial, you learned how to:
+
+- [Summary of learning objective 1]
+- [Summary of learning objective 2]
+- [Summary of learning objective 3]
+
+## Next steps
+<!-- REQUIRED
+
+Suggest follow-up tutorials, related features to explore, or ways to expand on what they built.
+-->
+
+- [Link to follow-up tutorial or next logical step]
+- [Link to related feature to explore]
+- [Suggestion for expanding on what was built]
+
+## Related pages
+<!-- REQUIRED
+
+Links to related documentation such as conceptual topics, reference material, how-to guides, or troubleshooting resources.
+-->
+
+- [Link to conceptual overview]
+- [Link to reference material]
+- [Link to related how-to guide]
+
+<!--
+Learn more about:
+- Required elements: https://www.elastic.co/docs/contribute-docs/content-types/tutorials#required-elements
+- Optional elements: https://www.elastic.co/docs/contribute-docs/content-types/tutorials#optional-elements
+- Best practices: https://www.elastic.co/docs/contribute-docs/content-types/tutorials#best-practices
+-->

contribute-docs/content-types/how-tos.md

@@ -6,7 +6,7 @@ description: "Guidelines for writing effective how-to guides in the Elastic docu
 
 This page provides guidelines for writing effective how-to guides in the Elastic docs.
 
-## What is a how-to guide?
+## What is a how-to guide
 
 How-to guides contain a short set of instructions to be carried out, in sequence, to accomplish a specific task. You can think of it like a cooking recipe.
 
@@ -17,7 +17,8 @@ How-to guides include two essential components:
 
 How-to guides focus on a single, self-contained task. For longer procedural content, use a tutorial.
 
-% TODO: Add eventual snippet that disambiguates how-tos, tutorials, and quickstarts -->
+::::{include} /contribute-docs/content-types/_snippets/how-to-tutorial-disambiguation-note.md
+::::
 
 ## Best practices
 

contribute-docs/content-types/tutorials.md

@@ -0,0 +1,98 @@
+---
+description: "Guidelines for writing effective tutorials in the Elastic documentation."
+---
+
+# Tutorials
+
+This page provides guidelines for writing effective tutorials in the Elastic docs.
+
+## What is a tutorial
+
+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](/contribute-docs/content-types/how-tos.md), 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
+
+::::{include} /contribute-docs/content-types/_snippets/how-to-tutorial-disambiguation-note.md
+::::
+
+## Best practices
+
+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](#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!
+  :::
+
+## Structure of a tutorial
+
+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.
+
+### Required elements
+
+The following elements are required in tutorials:
+
+- A consistent **filename:** Use descriptive patterns like `*-tutorial.md`.
+  - For example: `ingest-pipeline-tutorial.md`
+- Appropriate **[frontmatter](https://elastic.github.io/docs-builder/syntax/frontmatter/):**
+  - `applies_to:` [Tags](https://elastic.github.io/docs-builder/syntax/applies) for versioning/availability info per the [cumulative docs guidelines](/contribute-docs/how-to/cumulative-docs/index.md)
+  - `description`: A brief summary of what users will learn
+  - `product`: The relevant Elastic product(s) used in the tutorial
+% TODO once we have structured types  - The `type` field set to `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](https://elastic.github.io/docs-builder/syntax/stepper/) 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](https://elastic.github.io/docs-builder/syntax/code/#code-callouts):** 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.
+
+### Optional elements
+
+Include the following when they add value:
+
+- **[Screenshots](https://elastic.github.io/docs-builder/syntax/images/#screenshots):** Add visual aids for UI-based steps when they improve clarity. Use screenshots sparingly as they require maintenance.
+- **Explanatory callouts:** Use [admonitions](https://elastic.github.io/docs-builder/syntax/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.
+% TODO: reviewer I've made the summary optional, because if the overview already lists learning objectives clearly, a summary that just repeats them feels redundant. The tutorial's value is in the journey, not bookending it with the repetive information. 🤺
+
+## Template
+
+To get started writing your tutorial, use the [template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/tutorial-template.md).
+
+## Examples
+
+Here are some examples of well-structured tutorials in the Elastic documentation:
+
+- [Tutorial: Threat hunting with {{esql}}](/solutions/security/esql-for-security/esql-threat-hunting-tutorial.md): A **scenario-driven** tutorial that teaches {{esql}} through a realistic cybersecurity scenario, with extensive code annotations.
+- [{{esql}} for search tutorial](elasticsearch://reference/query-languages/esql/esql-search-tutorial.md): A **feature-focused** tutorial that systematically teaches search concepts using {{esql}}, from basic text matching to AI-powered semantic search, with subsections breaking down complex topics.
+
+% TODO: Add links to 2-3 exemplary tutorials in the docs

contribute-docs/toc.yml

@@ -7,6 +7,7 @@ toc:
     children:
       - file: index.md
       - file: how-tos.md
+      - file: tutorials.md
   - folder: how-to
     children:
       - file: index.md