Create content types overview, add how-to guide + template

contribute-docs/content-types/_snippets/templates/how-to-template.md

@@ -0,0 +1,105 @@
+---
+description: "A concise summary of the page highlighting what the task accomplishes, fit for search results and tooltips."
+applies_to:
+  stack:
+  serverless:
+type: how-to
+product:
+---
+
+<!-- Copy and paste this template to get started writing your how-to guide, deleting the instructions and comments from your final page.
+
+For complete guidance, refer to [the how-to guide](https://www.elastic.co/docs/contribute-docs/content-types/how-tos).
+
+-->
+
+# How to [action verb describing the task]
+<!-- REQUIRED
+
+A precise description of the task using an action verb 
+
+Example: Run Elasticsearch in Docker
+-->
+
+<!-- REQUIRED
+
+Introduction
+
+A brief summary of what the guide accomplishes and what the user will achieve -->
+
+## Before you begin
+<!--
+REQUIRED
+
+- Assume basic feature access.
+- You can also link to background knowledge or highlight known pitfalls.
+-->
+
+- [Permission or access requirement]
+- [Required data or configuration]
+- [Link to background knowledge if helpful]
+
+## Task name
+
+<!--
+REQUIRED
+
+- Numbered instructions that begin with imperative verb phrases
+- Keep each step focused on a single action
+-->
+
+<!-- Option 1: Simple numbered list for shorter how-tos with straightforward steps -->
+
+1. [First step - begin with an imperative verb]
+
+2. [Second step - begin with an imperative verb]
+
+3. [Third step - begin with an imperative verb]
+
+<!--
+Option 2: Stepper component for longer how-tos with complex steps
+
+See: https://elastic.github.io/docs-builder/syntax/stepper/
+-->
+
+```markdown
+:::::{stepper}
+
+::::{step} [Step title]
+[Step description or instruction]
+::::
+
+::::{step} [Step title]
+[Step description or instruction]
+::::
+
+::::{step} [Step title]
+[Step description or instruction]
+::::
+
+:::::
+```
+
+## Next steps
+<!-- RECOMMENDED
+
+Suggestions for what users can do after completing the task -->
+
+- [Follow-up task or next logical step]
+- [Another potential next step]
+
+## Related pages
+<!-- RECOMMENDED
+
+Links to related documentation such as conceptual topics, reference material, or other how-to guides -->
+
+- [Link to conceptual topic]
+- [Link to reference material]
+- [Link to related how-to guide]
+
+<!--
+Learn more about:
+- Required elements: https://www.elastic.co/docs/contribute-docs/content-types/how-tos#required-elements
+- Recommended elements: https://www.elastic.co/docs/contribute-docs/content-types/how-tos#recommended-elements
+- Optional elements: https://www.elastic.co/docs/contribute-docs/content-types/how-tos#optional-elements
+-->

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

@@ -0,0 +1,84 @@
+---
+description: "Guidelines for writing effective how-to guides in the Elastic documentation."
+---
+
+# How-to guides
+
+This page provides guidelines for writing effective how-to guides in the Elastic docs.
+
+## 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.
+
+How-to guides include two essential components:
+
+- A set of **requirements**
+- A sequence of **steps** to follow to accomplish a specific task
+
+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 -->
+
+## Best practices
+
+When you create how-to guides, follow these best practices:
+
+- **Focus on the user goal:** Organize the content around what users need to accomplish, rather than the tool capabilities.
+- **Write recipes, not lessons:** Explain only the information users need to complete the task. Avoid defining concepts or describing why something works unless it’s essential. Add useful context to a "Related pages" or "Learn more" section instead.
+- **Keep it focused:** A how-to guide should be scoped to a single, well-defined task. As a rule of thumb, if you need more than 10 overall steps, use the tutorial format.
+- **Show alternative approaches:** When multiple valid solutions exist, show the options users might choose. For example:
+  - If the same step can be carried out in the UI or with an API, use [tabs](https://elastic.github.io/docs-builder/syntax/tabs/#tab-groups) to show both options.
+  - If instructions differ per deployment type or version, use an [applies-switch](https://elastic.github.io/docs-builder/syntax/applies-switch/) to show the variations.
+- **Skip edge cases:** Focus on the typical, primary use case, and avoid documenting rare or non-standard variations.
+- **Test your steps:** Authors and reviewers should follow the instructions from start to finish to identify errors, missing steps, or unclear language.
+
+## Structure of a how-to guide
+
+To help users quickly find and follow instructions, how-to guides use a consistent structure. A predictable format improves clarity, reduces confusion, and makes the guide easier to use.
+
+### Required elements
+
+The following elements are required in how-to guides:
+
+- A consistent **filename:** Use action verb patterns like `create-*.md`, `configure-*.md`, or `troubleshoot-*.md`.
+  - For example: `run-elasticsearch-docker.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 the page fit for search results and tooltips
+  - `product`: The relevant Elastic product(s) used in the how-to
+% TODO once we have structured types  - The `type` field set to `how-to`
+- A clear **title:** A precise description of the task using an action verb
+  - For example, "Run {{es}} in Docker"
+- An **introduction:** Briefly explain what the guide helps the user accomplish and the outcome they can expect.
+- A **Before you begin** section: List any special permissions or data/configuration needed. Assume basic feature access. You can also link to background knowledge or highlight known pitfalls.
+- A set of **steps:** Numbered instructions that begin with imperative verb phrases. Keep each step focused on a single action.
+  :::{tip}
+  Use an [ordered list](https://elastic.github.io/docs-builder/syntax/lists/#ordered-list) for simple, linear steps. For longer how-tos or those with complex steps, use the [stepper component](https://elastic.github.io/docs-builder/syntax/stepper/).
+  :::
+- **Success checkpoints:** Include confirmation steps that show users whether critical actions succeeded before moving on.
+
+### Recommended sections
+
+Include the following sections in most how-to guides:
+
+- **Next steps:** Suggestions for what users can do next after completing the task.
+- **Related pages:** Links to related documentation such as conceptual topics, reference material, troubleshooting, or other how-to guides.
+
+### Optional elements
+
+Consider including the following when they add value:
+
+- **[Code annotations](https://elastic.github.io/docs-builder/syntax/code/#code-callouts):** Annotate important lines within code blocks.
+- **[Screenshots](https://elastic.github.io/docs-builder/syntax/images/#screenshots):** Add visual aids for UI tasks when context is hard to describe in words. Use screenshots sparingly as they're hard to maintain.
+- **Error handling:** Mention common errors and how to resolve them.
+
+## Template
+
+To get started writing your how-to guide, use the [template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/how-to-template.md).
+
+% ## Examples
+
+% Here are some examples of well-structured how-to guides in the Elastic documentation:
+
+% TODO: Add links to 2-3 exemplary how-to guides in the docs
+

contribute-docs/content-types/index.md

@@ -0,0 +1,50 @@
+---
+navigation_title: "Content types"
+description: "Overview of guidelines for choosing the appropriate content types in the Elastic documentation."
+---
+
+# Elastic Docs content types
+
+Content types ensure the Elastic Docs are well-structured, consistent, and complete. When we use the right content type, we make it easier for users to find the information they need and efficiently complete tasks. 
+
+To help you quickly get started, each content type includes its own guidelines, best practices, and templates.
+
+Before you start drafting a new docs page, identify the appropriate content type for your page.
+Use these guidelines as a framework, not a rulebook. You should adapt structure and syntax where necessary to best serve users, but you should rarely need to deviate from the best practices.
+
+:::{tip}
+Need help choosing a content type or structuring a new page? Reach out to the docs team using the `@elastic/docs` handle in GitHub or post in the [community docs channel](https://elasticstack.slack.com/archives/C09EUND5612). (Elasticians can also use the internal [#docs](https://elastic.slack.com/archives/C0JF80CJZ) Slack channel.)
+:::
+
+## Mixing different content types
+
+Some documentation pages combine multiple content types.
+
+Mixing different types is fine as long as each section is clearly delineated and serves a distinct purpose. For example, a page about configuring authentication might include:
+
+1. A brief overview of authentication concepts (explanation)
+2. Step-by-step instructions to set up authentication (how-to)
+3. A reference table of authentication settings (reference)
+
+This works because each section is clearly separated and serves a distinct purpose. You shouldn't embed the settings table in the middle of the instructions, or interrupt the steps with conceptual explanations. This would break the flow and make it hard to scan the page for specific information.
+
+When mixing content types, ensure that the overall structure and flow remain clear and logical for users. Use headings and sections to delineate different content types as needed.
+
+:::{note}
+The exception to this rule is the tutorial content type, which weaves explanatory and background information throughout the step-by-step instructions. This is because tutorials are focused on teaching a broader concept or workflow, rather than completing a specific task as fast as possible.
+
+A tutorial should always be a standalone page, meaning it should have only one content type: `tutorial`.
+
+% TODO add this once we have structured types:
+
+% the frontmatter should only specify `type: tutorial`.
+:::
+
+## Guidelines per content type
+
+- [How-to guides](how-tos.md)
+% - [Tutorial](tutorials.md)
+
+## Templates per content type
+
+Refer to [our templates](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/how-to-template.md) for each content type to get started quickly.

contribute-docs/toc.yml

@@ -3,6 +3,10 @@ toc:
   - file: on-the-web.md
   - file: locally.md
   - file: syntax-quick-reference.md
+  - folder: content-types
+    children:
+      - file: index.md
+      - file: how-tos.md
   - folder: how-to
     children:
       - file: index.md