-
Notifications
You must be signed in to change notification settings - Fork 193
[Contribution initiative] Add tutorial content type #4462
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
Vale Linting ResultsSummary: 1 warning, 13 suggestions found
|
| 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. |
🔍 Preview links for changed docs |
| - **[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} |
There was a problem hiding this comment.
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! |
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
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.
Closes https://github.com/elastic/docs-team/issues/114
DONE:TODO:Generative AI disclosure
2.Tool(s) and model(s) used:
Claude Code, Opus 4.1 for autocomplete on steroids and grunt work automation