From 9b440b55057409584b1cf21232214ce5e93b26d7 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Wed, 17 Dec 2025 17:35:35 +0100 Subject: [PATCH] Add Overview content type --- .../_snippets/templates/overview-template.md | 115 ++++++++++++++++++ contribute-docs/content-types/index.md | 3 +- contribute-docs/content-types/overviews.md | 94 ++++++++++++++ contribute-docs/toc.yml | 1 + 4 files changed, 212 insertions(+), 1 deletion(-) create mode 100644 contribute-docs/content-types/_snippets/templates/overview-template.md create mode 100644 contribute-docs/content-types/overviews.md diff --git a/contribute-docs/content-types/_snippets/templates/overview-template.md b/contribute-docs/content-types/_snippets/templates/overview-template.md new file mode 100644 index 0000000000..e33e3b49ad --- /dev/null +++ b/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: +--- + + + +# [Feature or concept name] + + + + +## Use cases + + +## How it works + + +## Key concepts + + +## Background + + +## [Comparison or decision section] + + +## Next steps + + +- [Link to getting started guide or tutorial] +- [Link to a how-to guide for a common task] + +## Related pages + + +- [Link to how-to guide] +- [Link to reference material] +- [Link to related overview] + + + diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md index cf5aff284c..dcc8d3245c 100644 --- a/contribute-docs/content-types/index.md +++ b/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. diff --git a/contribute-docs/content-types/overviews.md b/contribute-docs/content-types/overviews.md new file mode 100644 index 0000000000..efefd6bbf4 --- /dev/null +++ b/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 + diff --git a/contribute-docs/toc.yml b/contribute-docs/toc.yml index 6287e6598c..6d84b29c5e 100644 --- a/contribute-docs/toc.yml +++ b/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