Add Overview content type

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

@@ -0,0 +1,115 @@
+---
+description: "A concise summary highlighting what the feature or concept is and why it matters, fit for search results and tooltips."
+applies_to:
+  stack:
+  serverless:
+type: overview
+product:
+---
+
+<!-- Copy and paste this template to get started writing your overview page, deleting the instructions and comments from your final page.
+
+For complete guidance, refer to [the overview guide](https://www.elastic.co/docs/contribute-docs/content-types/overviews).
+
+-->
+
+# [Feature or concept name]
+<!-- REQUIRED
+
+A concise, descriptive name for the feature or concept.
+
+Example: Inference processing
+-->
+
+<!-- REQUIRED
+
+Introduction
+
+Explain what this feature or concept is and why it matters to users. Your introduction should:
+
+- Answer "What is it?" at a high level
+- Establish the scope — what this overview covers
+- Optionally clarify what's out of scope if that helps set expectations
+- Help readers quickly determine if they're in the right place
+
+Use the inverted pyramid: lead with the most important information, then add detail. -->
+
+## Use cases
+<!-- RECOMMENDED
+
+Describe concrete scenarios or examples showing how the feature or concept applies in practice. Help users understand when and why they would use this.
+
+Example structure:
+### [Use case name]
+[Brief description of the use case and its value]
+-->
+
+## How it works
+<!-- RECOMMENDED
+
+Explain the underlying mechanism, workflow, or architecture. Consider including a diagram to illustrate the concept.
+
+Example:
+The diagram below shows how [feature] processes [data/requests]:
+
+[Mermaid diagram or image]
+
+- [Key point about the workflow]
+- [Another key point]
+-->
+
+## Key concepts
+<!-- OPTIONAL
+
+Define important terms or explain core concepts that are central to understanding this feature. Use this section when terminology might be unfamiliar to users.
+
+- **[Term 1]:** [Definition]
+- **[Term 2]:** [Definition]
+-->
+
+## Background
+<!-- OPTIONAL
+
+Provide context that helps readers understand the concept more deeply. This might include:
+
+- Historical context (where the idea originated, why it works the way it does)
+- Industry context (relevant standards, common patterns)
+- Design decisions (why certain choices were made, what alternatives exist)
+
+Only include this section when context adds meaningful value to understanding. -->
+
+## [Comparison or decision section]
+<!-- OPTIONAL
+
+When helping users choose between options, use this section to compare features, trade-offs, or use cases. Consider using a table for clarity.
+
+| Option | Best for | Trade-offs |
+|--------|----------|------------|
+| [Option A] | [Use case] | [Trade-off] |
+| [Option B] | [Use case] | [Trade-off] |
+-->
+
+## Next steps
+<!-- RECOMMENDED
+
+Suggestions for what users can do after reading this overview -->
+
+- [Link to getting started guide or tutorial]
+- [Link to a how-to guide for a common task]
+
+## Related pages
+<!-- RECOMMENDED
+
+Links to related documentation such as how-to guides, reference material, or other overviews -->
+
+- [Link to how-to guide]
+- [Link to reference material]
+- [Link to related overview]
+
+<!--
+Learn more about:
+- Required elements: https://www.elastic.co/docs/contribute-docs/content-types/overviews#required-elements
+- Recommended elements: https://www.elastic.co/docs/contribute-docs/content-types/overviews#recommended-elements
+- Optional elements: https://www.elastic.co/docs/contribute-docs/content-types/overviews#optional-elements
+-->
+

contribute-docs/content-types/index.md

@@ -43,8 +43,9 @@ A tutorial should always be a standalone page, meaning it should have only one c
 ## Guidelines per content type
 
 - [How-to guides](how-tos.md)
+- [Overviews](overviews.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.
+Refer to [our templates](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/) for each content type to get started quickly.

contribute-docs/content-types/overviews.md

@@ -0,0 +1,94 @@
+---
+description: "Guidelines for writing useful and comprehensive overview pages in the Elastic documentation."
+applies_to:
+  stack:
+  serverless:
+---
+
+# Overviews
+
+This page provides guidelines for writing effective overview pages in the Elastic docs.
+
+## What is an overview
+
+An overview provides conceptual information that helps users understand a feature, product, or concept. It answers two fundamental questions:
+
+- **What is it?**
+- **How does it work?**
+
+Readers of overview pages are typically in a learning state rather than a goal-oriented or problem-solving state. They are often first-time users who want to get up and running quickly. Having effective overview content builds trust and confidence in our products.
+
+Overviews serve several purposes:
+
+- Explain what something is and why it matters.
+- Help users navigate to the right content for their needs.
+- Clarify how components, features, or concepts relate to each other.
+- Help users choose between options or understand trade-offs.
+
+## Best practices
+
+When you create overview pages, follow these best practices:
+
+- **Focus on a single concept:** Each overview should be dedicated to one concept, feature, or topic. If you find yourself explaining a second concept in depth, create a separate overview and link to it.
+- **Lead with user value:** Start by explaining why the feature or concept matters to the user, not just what it does.
+- **Use the inverted pyramid:** Begin with the most important information at a high level, then progressively add detail. This lets readers grasp the essentials quickly and dive deeper as needed.
+- **Keep it conceptual:** Focus on explaining ideas, not on step-by-step instructions. Avoid instructional or reference content. Link to how-to guides and reference pages instead.
+- **Answer the key questions:** Ensure your overview addresses the fundamental questions: What is it? Why does it matter? How does it work? When would I use it?
+- **Use concrete examples:** Abstract concepts become clearer when illustrated with real-world scenarios or use cases.
+- **Provide visual aids:** Diagrams, flowcharts, and architecture illustrations help users grasp complex relationships.
+- **Avoid duplication:** Don't repeat detailed information that belongs in reference or how-to pages. Link to those pages instead.
+
+## Structure of an overview
+
+To help users quickly understand a feature or concept, overviews use a consistent structure. A predictable format improves comprehension and makes the content easier to navigate.
+
+### Required elements
+
+The following elements are required in overview pages:
+
+- A consistent **filename:** Use descriptive noun-based patterns. Common patterns include:
+  - `[feature-name].md` (for example, `text-embedding.md`)
+  - `[concept].md` (for example, `data-streams.md`)
+  - `index.md` for section landing pages
+- 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) covered in the overview
+% TODO once we have structured types  - The `type` field set to `overview`
+- A clear **title:** A concise, descriptive name for the feature or concept
+  - For example, "Text embedding" or "Data streams"
+- An **introduction:** Explain what the feature or concept is and why it matters to users. This should:
+  - Answer "What is it?" at a high level.
+  - Establish the scope: what the overview covers and, optionally, what it doesn't.
+  - Help readers quickly determine if they're in the right place.
+- **Core content sections:** The body of the overview explaining how it works, key concepts, components, or use cases. Structure these sections based on what users need to understand.
+
+### Recommended sections
+
+Include the following sections in most overview pages:
+
+- **Use cases or examples:** Concrete scenarios showing how the feature or concept applies in practice.
+- **How it works:** A section explaining the underlying mechanism, workflow, or architecture. Consider including a diagram.
+- **Next steps:** Suggestions for what users can do next, such as getting started guides or tutorials.
+- **Related pages:** Links to related documentation such as how-to guides, reference material, or other overviews.
+
+### Optional elements
+
+Consider including the following when they add value:
+
+- **Background or context:** Historical context, industry context, or an explanation of why something was designed a certain way. This is especially useful for complex concepts with non-obvious design decisions.
+- **[Diagrams](https://elastic.github.io/docs-builder/syntax/diagrams/):** Architecture diagrams, flowcharts, or other visual aids to illustrate concepts and relationships.
+- **Comparison tables:** When helping users choose between options, use tables to compare features, trade-offs, or use cases.
+- **[Tabs](https://elastic.github.io/docs-builder/syntax/tabs/):** When explaining variations (such as different deployment types or product tiers), use tabs to show the differences.
+- **Key terminology:** Define important terms if they're central to understanding the concept.
+
+## Template
+
+To get started writing your overview page, use the [template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/overview-template.md).
+
+% ## Examples
+
+% Here are some examples of well-structured overview pages in the Elastic documentation:
+
+% TODO: Add links to 2-3 exemplary overview pages in the docs
+

contribute-docs/toc.yml

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