Skip to content

Conversation

@leemthompo
Copy link
Contributor

@leemthompo leemthompo commented Dec 29, 2025

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

DONE:

  • 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 😀)

TODO:

  • Template

Generative AI disclosure

  1. 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
Copy link
Contributor

github-actions bot commented Dec 29, 2025

Vale Linting Results

Summary: 1 warning, 13 suggestions found

⚠️ Warnings (1)
File Line Rule Message
contribute-docs/content-types/tutorials.md 85 Elastic.DontUse Don't use 'just'.
💡 Suggestions (13)
File Line Rule Message
contribute-docs/content-types/_snippets/templates/tutorial-template.md 2 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/_snippets/templates/tutorial-template.md 16 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/_snippets/templates/tutorial-template.md 37 Elastic.FutureTense 'you'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/_snippets/templates/tutorial-template.md 42 Elastic.FutureTense 'you'll be' 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/_snippets/templates/tutorial-template.md 44 Elastic.EmDashes Don't put a space before or after a dash.
contribute-docs/content-types/_snippets/templates/tutorial-template.md 58 Elastic.FutureTense 'You'll need' 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 39 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 39 Elastic.Exclamation Use exclamation points sparingly. Consider removing the exclamation point.
contribute-docs/content-types/tutorials.md 44 Elastic.Wordiness Consider using 'complete' instead of 'successfully complete'.
contribute-docs/content-types/tutorials.md 44 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 44 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 54 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 60 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.

@github-actions
Copy link
Contributor

github-actions bot commented Dec 29, 2025

- **[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}
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: I've nested admonitions: love it or hate it?

- **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!
Copy link
Contributor Author

@leemthompo leemthompo Dec 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use exclamation points sparingly.

One exclamation point is as sparing as one can be 😄


## Examples

Here are some examples of well-structured tutorials in the Elastic documentation:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants