[Contribution initiative] Add tutorial content type #4462

leemthompo · 2025-12-29T16:07:50Z

Closes https://github.com/elastic/docs-team/issues/114

Drafted main guide page
Disambiguation snippet included in both how-tos.md and tutorials.md
Two example tutorials linked (provisionally ES|QL threat hunting and ES|QL search, will hive mind for alternative examples 😀)
Template

Generative AI disclosure

Did you use a generative AI (GenAI) tool to assist in creating this contribution?

Yes
No

2.Tool(s) and model(s) used:

Claude Code, Opus 4.1 for autocomplete on steroids and grunt work automation

github-actions · 2025-12-29T16:08:53Z

Vale Linting Results

Summary: 1 warning, 8 suggestions found

⚠️ Warnings (1)

File	Line	Rule	Message
contribute-docs/content-types/tutorials.md	84	Elastic.DontUse	Don't use 'just'.

💡 Suggestions (8)

File	Line	Rule	Message
contribute-docs/content-types/_snippets/templates/tutorial-template.md	44	Elastic.EmDashes	Don't put a space before or after a dash.
contribute-docs/content-types/tutorials.md	34	Elastic.Wordiness	Consider using 'complete' instead of 'successfully complete'.
contribute-docs/content-types/tutorials.md	34	Elastic.FutureTense	'they'll learn' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/content-types/tutorials.md	34	Elastic.FutureTense	'they'll achieve' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/content-types/tutorials.md	45	Elastic.FutureTense	'will learn' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/content-types/tutorials.md	53	Elastic.FutureTense	'will learn' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/content-types/tutorials.md	101	Elastic.FutureTense	'They'll find' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/content-types/tutorials.md	101	Elastic.Exclamation	Use exclamation points sparingly. Consider removing the exclamation point.

github-actions · 2025-12-29T16:10:00Z

🔍 Preview links for changed docs

leemthompo · 2025-12-29T16:15:08Z

contribute-docs/content-types/tutorials.md

+- **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!


Use exclamation points sparingly.

One exclamation point is as sparing as one can be 😄

leemthompo · 2025-12-29T16:17:16Z

contribute-docs/content-types/tutorials.md

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


Zero attachments to these specifically, and we wouldn't want two ESQL examples here, but they illustrate the two different flavors I've tried to tease out here (feature-focused versus scenario-driven tutorials) and they hew pretty close to the best practices.

KOTungseth

This is shaping up nicely! Thank you for tackling tutorials. I left a bunch of suggestions and recommendations.

We should also add a link to this page on the Elastic Docs content types page.

KOTungseth · 2026-01-09T20:55:51Z

contribute-docs/content-types/tutorials.md

+
+# Tutorials
+
+This page provides guidelines for writing effective tutorials in the Elastic docs. This page and its associated template can be used by humans and LLMs to draft new tutorials, or to evaluate existing pages.


Suggested change

This page provides guidelines for writing effective tutorials in the Elastic docs. This page and its associated template can be used by humans and LLMs to draft new tutorials, or to evaluate existing pages.

To create tutorials or improve existing tutorials, use the standards and best practices in the guidelines and template. The guidelines apply to content authored by human contributors and automated systems.

KOTungseth · 2026-01-09T20:56:18Z

contribute-docs/content-types/tutorials.md

+
+This page provides guidelines for writing effective tutorials in the Elastic docs. This page and its associated template can be used by humans and LLMs to draft new tutorials, or to evaluate existing pages.
+
+Use this page to:


Suggested change

Use this page to:

Use the tutorial guidelines and template to complete the following:

KOTungseth · 2026-01-09T20:56:35Z

contribute-docs/content-types/tutorials.md

+
+Use this page to:
+
+- Draft a new tutorial by copying and pasting the [template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/tutorial-template.md)


Suggested change

- Draft a new tutorial by copying and pasting the [template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/tutorial-template.md)

- Create a tutorial by copying and pasting the [template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/tutorial-template.md)

KOTungseth · 2026-01-09T20:57:04Z

contribute-docs/content-types/tutorials.md

+Use this page to:
+
+- Draft a new tutorial by copying and pasting the [template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/tutorial-template.md)
+- Understand the structure and best practices for tutorials before you write one


Suggested change

- Understand the structure and best practices for tutorials before you write one

- Understand the required structure, scope, and best practices for tutorials

KOTungseth · 2026-01-09T20:57:18Z

contribute-docs/content-types/tutorials.md

+
+- Draft a new tutorial by copying and pasting the [template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/tutorial-template.md)
+- Understand the structure and best practices for tutorials before you write one
+- Evaluate existing tutorials or drafts against the standards outlined here


Suggested change

- Evaluate existing tutorials or drafts against the standards outlined here

- Evaluate existing tutorials or drafts against the standards

KOTungseth · 2026-01-09T21:25:09Z

contribute-docs/content-types/tutorials.md

+
+### Required elements
+
+Every tutorial must include the following elements:


Suggested change

Every tutorial must include the following elements:

Review the required elements that every tutorial must include.

KOTungseth · 2026-01-09T21:28:12Z

contribute-docs/content-types/tutorials.md

+
+Every tutorial must include the following elements:
+
+1. A consistent **filename:** Use descriptive patterns like `*-tutorial.md`.


We should eventually link to the not yet documented file/folder name guidelines.

KOTungseth · 2026-01-09T21:29:53Z

contribute-docs/content-types/tutorials.md

+   - Required prior knowledge or skills
+   - Software, hardware, or access requirements
+   - Data sets or environments to set up
+   - Estimated time to complete (optional but helpful)


Do we want to make this optional?

KOTungseth · 2026-01-09T21:30:49Z

contribute-docs/content-types/tutorials.md

+
+9. **Next steps:** Suggest follow-up tutorials, related features to explore, or ways to expand on what they built.
+
+10. **Related pages:** Links to related documentation such as conceptual topics, reference material, how-to guides, or troubleshooting resources.


What about non docs resources? Such as education content?

KOTungseth · 2026-01-09T21:36:15Z

contribute-docs/content-types/tutorials.md

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


Since this is linked above, do we need it here?

leemthompo added 2 commits December 29, 2025 16:57

Add tutorial content type

2630ade

placate the linter gods

82d76bc

leemthompo self-assigned this Dec 29, 2025

github-actions bot deployed to docs-preview December 29, 2025 16:08 View deployment

leemthompo commented Dec 29, 2025

View reviewed changes

leemthompo added 2 commits December 30, 2025 12:09

Add template

03f27a6

tighten up guide

2ab7f56

github-actions bot deployed to docs-preview December 30, 2025 11:10 View deployment

leemthompo added 2 commits January 5, 2026 16:06

Fix lint warnings

d83d9dd

delete vague verbiage

be17024

github-actions bot deployed to docs-preview January 5, 2026 15:07 View deployment

tense

ce19eaa

github-actions bot deployed to docs-preview January 5, 2026 15:37 View deployment

improve disambiguation, delete nested admonition

20aed8d

github-actions bot deployed to docs-preview January 5, 2026 16:08 View deployment

refactor intro, focus on use cases for the doc

d58185e

github-actions bot deployed to docs-preview January 6, 2026 17:59 View deployment

KOTungseth reviewed Jan 9, 2026

View reviewed changes


		## Examples

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


		# Tutorials

		This page provides guidelines for writing effective tutorials in the Elastic docs. This page and its associated template can be used by humans and LLMs to draft new tutorials, or to evaluate existing pages.

	This page provides guidelines for writing effective tutorials in the Elastic docs. This page and its associated template can be used by humans and LLMs to draft new tutorials, or to evaluate existing pages.
	To create tutorials or improve existing tutorials, use the standards and best practices in the guidelines and template. The guidelines apply to content authored by human contributors and automated systems.


		This page provides guidelines for writing effective tutorials in the Elastic docs. This page and its associated template can be used by humans and LLMs to draft new tutorials, or to evaluate existing pages.

		Use this page to:

	Use this page to:
	Use the tutorial guidelines and template to complete the following:


		Use this page to:

		- Draft a new tutorial by copying and pasting the [template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/tutorial-template.md)

	- Draft a new tutorial by copying and pasting the [template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/tutorial-template.md)
	- Create a tutorial by copying and pasting the [template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/tutorial-template.md)

	- Understand the structure and best practices for tutorials before you write one
	- Understand the required structure, scope, and best practices for tutorials

	- Evaluate existing tutorials or drafts against the standards outlined here
	- Evaluate existing tutorials or drafts against the standards


		### Required elements

		Every tutorial must include the following elements:

	Every tutorial must include the following elements:
	Review the required elements that every tutorial must include.


		Every tutorial must include the following elements:

		1. A consistent filename: Use descriptive patterns like `*-tutorial.md`.


		9. Next steps: Suggest follow-up tutorials, related features to explore, or ways to expand on what they built.

		10. Related pages: Links to related documentation such as conceptual topics, reference material, how-to guides, or troubleshooting resources.

[Contribution initiative] Add tutorial content type #4462

Are you sure you want to change the base?

[Contribution initiative] Add tutorial content type #4462

Uh oh!

Conversation

leemthompo commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Generative AI disclosure

Uh oh!

github-actions bot commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Linting Results

Uh oh!

github-actions bot commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

leemthompo Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KOTungseth left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

leemthompo commented Dec 29, 2025 •

edited

Loading

github-actions bot commented Dec 29, 2025 •

edited

Loading

github-actions bot commented Dec 29, 2025 •

edited

Loading

leemthompo Dec 29, 2025 •

edited

Loading