From 5b3ccd40079a32e319cf20865fd407c43d878bd5 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 8 Dec 2025 13:03:51 +0000 Subject: [PATCH 01/20] Create content types overview, add how-to guide + template --- .../_snippets/templates/how-to-template.md | 104 ++++++++++++++++++ contribute-docs/content-types/how-tos.md | 84 ++++++++++++++ contribute-docs/content-types/index.md | 47 ++++++++ contribute-docs/toc.yml | 4 + 4 files changed, 239 insertions(+) create mode 100644 contribute-docs/content-types/_snippets/templates/how-to-template.md create mode 100644 contribute-docs/content-types/how-tos.md create mode 100644 contribute-docs/content-types/index.md diff --git a/contribute-docs/content-types/_snippets/templates/how-to-template.md b/contribute-docs/content-types/_snippets/templates/how-to-template.md new file mode 100644 index 0000000000..1c2a1113fb --- /dev/null +++ b/contribute-docs/content-types/_snippets/templates/how-to-template.md @@ -0,0 +1,104 @@ +--- +description: "A nice summary of the page fit for search results and tooltips." +applies_to: + stack: + serverless: +type: how-to +product: +--- + + + +# How to [action verb describing the task] + + + + +## Before you begin + + +- [Permission or access requirement] +- [Required data or configuration] +- [Link to background knowledge if helpful] + +## 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] + + + +```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 + + +- [Follow-up task or next logical step] +- [Another potential next step] + +## Related pages + + +- [Link to conceptual topic] +- [Link to reference material] +- [Link to related how-to guide] + + diff --git a/contribute-docs/content-types/how-tos.md b/contribute-docs/content-types/how-tos.md new file mode 100644 index 0000000000..0129d9c80d --- /dev/null +++ b/contribute-docs/content-types/how-tos.md @@ -0,0 +1,84 @@ +--- +navigation_title: "How-to guides" +--- + +# Writing how-to guides + +This page provides guidelines for writing effective how-to guides in Elastic documentation. To learn about other content types, refer to [](index.md). + +## What is a how-to guide? + +A how-to guide contains 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. + +It has two essential components: + +- A set of **requirements** +- A sequence of **steps** to follow + +This focus on a self-contained task is what defines a how-to guide and sets it apart from longer procedural guides, such as quickstarts or tutorials. + +% TODO: Add eventual snippet that disambiguates how-tos, tutorials, and quickstarts --> + +## Key principles + +There are a few key principles to keep in mind when drafting how-to guides: + +- **Focus on the user's goal:** Structure content around what users want to accomplish, not what the tool can do. +- **Write recipes, not lessons:** Don't define concepts or explain why things work, unless required for the task at hand. 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, consider breaking it into multiple how-to guides or 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 end to end, to catch errors, missing steps, and language issues. + +## Structure of a how-to guide + +How-to guides follow a consistent structure. The following sections outline the required, recommended, and optional elements. + +### Required elements + +The following elements are required in every how-to guide: + +- 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](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, "How to run {{es}} in Docker" +- An **introduction:** A brief summary of what the guide accomplishes and what the user will achieve. +- 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 the [stepper component](https://elastic.github.io/docs-builder/syntax/stepper/) for longer how-tos or those with complex steps. + ::: + +### 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, 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. +- **Success checkpoints:** Include confirmation steps that show users whether critical actions succeeded before moving on. +- **Error handling:** Mention common errors and how to resolve them. + +## Template + +You can use the [how-to template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/how-to-template.md) to get started writing your how-to guide. + +## 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 + diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md new file mode 100644 index 0000000000..257dce2ec2 --- /dev/null +++ b/contribute-docs/content-types/index.md @@ -0,0 +1,47 @@ +# Content types + +Content types help us write documentation that is well-structured and consistent. + +Each content type has its own guidelines and best practices. We also provide templates to help you get started quickly. + +## Using guidelines and templates + +When writing documentation, start by identifying 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 key _principles_. + +:::{tip} +Need help choosing or structuring a new page? Reach out to the docs team using the `@elastic/docs` handle in GitHub or post in the [#docs](https://elastic.slack.com/archives/C0JF80CJZ) Slack channel. +::: + +## Mixing different content types + +Some documentation pages may 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](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. \ No newline at end of file diff --git a/contribute-docs/toc.yml b/contribute-docs/toc.yml index 4c73e4e566..6287e6598c 100644 --- a/contribute-docs/toc.yml +++ b/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 From fa9d8825ece913801fa28486f3184120d06066c7 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 8 Dec 2025 13:13:55 +0000 Subject: [PATCH 02/20] fix link --- contribute-docs/content-types/how-tos.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute-docs/content-types/how-tos.md b/contribute-docs/content-types/how-tos.md index 0129d9c80d..1296c9a7ec 100644 --- a/contribute-docs/content-types/how-tos.md +++ b/contribute-docs/content-types/how-tos.md @@ -43,7 +43,7 @@ The following elements are required in every how-to guide: - 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](how-to/cumulative-docs/index.md) + - `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` From 8196936c319235c4901c77aa9f43b5253d9df74d Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 8 Dec 2025 13:21:30 +0000 Subject: [PATCH 03/20] vale fixes --- contribute-docs/content-types/how-tos.md | 2 +- contribute-docs/content-types/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/contribute-docs/content-types/how-tos.md b/contribute-docs/content-types/how-tos.md index 1296c9a7ec..e0d8510fb2 100644 --- a/contribute-docs/content-types/how-tos.md +++ b/contribute-docs/content-types/how-tos.md @@ -2,7 +2,7 @@ navigation_title: "How-to guides" --- -# Writing how-to guides +# How to write how-to guides This page provides guidelines for writing effective how-to guides in Elastic documentation. To learn about other content types, refer to [](index.md). diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md index 257dce2ec2..13217ba8c3 100644 --- a/contribute-docs/content-types/index.md +++ b/contribute-docs/content-types/index.md @@ -15,7 +15,7 @@ Need help choosing or structuring a new page? Reach out to the docs team using t ## Mixing different content types -Some documentation pages may combine multiple 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: From ebce32cf5af95a9e6fa5d266f72be4c63fe4650e Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 8 Dec 2025 13:26:26 +0000 Subject: [PATCH 04/20] language tweak --- contribute-docs/content-types/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md index 13217ba8c3..54e72ebb96 100644 --- a/contribute-docs/content-types/index.md +++ b/contribute-docs/content-types/index.md @@ -6,7 +6,7 @@ Each content type has its own guidelines and best practices. We also provide tem ## Using guidelines and templates -When writing documentation, start by identifying the appropriate content type for your page. +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 key _principles_. :::{tip} From 84a55bb15aa45e68cc1559e8081060c11dd2faef Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 8 Dec 2025 13:46:37 +0000 Subject: [PATCH 05/20] fix sentence --- contribute-docs/content-types/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md index 54e72ebb96..be4c4d6fcd 100644 --- a/contribute-docs/content-types/index.md +++ b/contribute-docs/content-types/index.md @@ -10,7 +10,7 @@ Before you start drafting a new docs page, identify the appropriate content type 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 key _principles_. :::{tip} -Need help choosing or structuring a new page? Reach out to the docs team using the `@elastic/docs` handle in GitHub or post in the [#docs](https://elastic.slack.com/archives/C0JF80CJZ) Slack channel. +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 [#docs](https://elastic.slack.com/archives/C0JF80CJZ) Slack channel. ::: ## Mixing different content types From 2328dd40ca8e532298288c622557b854eff50f16 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 9 Dec 2025 11:30:16 +0000 Subject: [PATCH 06/20] =?UTF-8?q?Tighten=20things=20up,=20Kaarina-style=20?= =?UTF-8?q?=F0=9F=92=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Kaarina Tungseth --- contribute-docs/content-types/how-tos.md | 26 ++++++++++++------------ contribute-docs/content-types/index.md | 8 ++++---- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/contribute-docs/content-types/how-tos.md b/contribute-docs/content-types/how-tos.md index e0d8510fb2..1867aff052 100644 --- a/contribute-docs/content-types/how-tos.md +++ b/contribute-docs/content-types/how-tos.md @@ -8,14 +8,14 @@ This page provides guidelines for writing effective how-to guides in Elastic doc ## What is a how-to guide? -A how-to guide contains 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 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. -It has two essential components: +How-to guides include two essential components: - A set of **requirements** -- A sequence of **steps** to follow +- A sequence of **steps** to follow to accomplish a specific task -This focus on a self-contained task is what defines a how-to guide and sets it apart from longer procedural guides, such as quickstarts or tutorials. +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 --> @@ -23,22 +23,22 @@ This focus on a self-contained task is what defines a how-to guide and sets it a There are a few key principles to keep in mind when drafting how-to guides: -- **Focus on the user's goal:** Structure content around what users want to accomplish, not what the tool can do. -- **Write recipes, not lessons:** Don't define concepts or explain why things work, unless required for the task at hand. 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, consider breaking it into multiple how-to guides or use the tutorial format. +- **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 end to end, to catch errors, missing steps, and language issues. +- **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 -How-to guides follow a consistent structure. The following sections outline the required, recommended, and optional elements. +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 every how-to guide: +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` @@ -49,7 +49,7 @@ The following elements are required in every how-to guide: % 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, "How to run {{es}} in Docker" -- An **introduction:** A brief summary of what the guide accomplishes and what the user will achieve. +- 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} @@ -61,7 +61,7 @@ The following elements are required in every how-to guide: 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, or other how-to guides. +- **Related pages:** Links to related documentation such as conceptual topics, reference material, troubleshooting, or other how-to guides. ### Optional elements @@ -74,7 +74,7 @@ Consider including the following when they add value: ## Template -You can use the [how-to template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/how-to-template.md) to get started writing your how-to guide. +To get started on writing your how-to guide, use the [how-to template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/how-to-template.md). ## Examples diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md index be4c4d6fcd..c612fb6876 100644 --- a/contribute-docs/content-types/index.md +++ b/contribute-docs/content-types/index.md @@ -1,13 +1,13 @@ -# Content types +# Elastic Docs content types -Content types help us write documentation that is well-structured and consistent. +Content types ensure the Elastic Docs are structured, consistent, and easy for users to follow. When we use the right content type, we make it easy for users to find the information they need and efficiently complete tasks. -Each content type has its own guidelines and best practices. We also provide templates to help you get started quickly. +To help you quickly get started, each content type includes its own guidelines, best practices, and templates. ## Using guidelines 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 key _principles_. +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 [#docs](https://elastic.slack.com/archives/C0JF80CJZ) Slack channel. From ecb155ee32d1609c769d55eaf01d547851ecded0 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 9 Dec 2025 11:38:24 +0000 Subject: [PATCH 07/20] Best practices, other cleanup --- contribute-docs/content-types/how-tos.md | 6 ++---- contribute-docs/content-types/index.md | 2 -- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/contribute-docs/content-types/how-tos.md b/contribute-docs/content-types/how-tos.md index 1867aff052..c3cf1511c2 100644 --- a/contribute-docs/content-types/how-tos.md +++ b/contribute-docs/content-types/how-tos.md @@ -19,9 +19,9 @@ How-to guides focus on a single, self-contained task. For longer procedural cont % TODO: Add eventual snippet that disambiguates how-tos, tutorials, and quickstarts --> -## Key principles +## Best practices -There are a few key principles to keep in mind when drafting how-to guides: +When you create how-to guides, use the following 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. @@ -36,8 +36,6 @@ There are a few key principles to keep in mind when drafting how-to guides: 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`. diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md index c612fb6876..a5e27f6817 100644 --- a/contribute-docs/content-types/index.md +++ b/contribute-docs/content-types/index.md @@ -4,8 +4,6 @@ Content types ensure the Elastic Docs are structured, consistent, and easy for u To help you quickly get started, each content type includes its own guidelines, best practices, and templates. -## Using guidelines 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. From f6bc40638c7b4e571702e35a1a64745114b0cb7b Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 9 Dec 2025 11:38:59 +0000 Subject: [PATCH 08/20] no need for immediate redirect --- contribute-docs/content-types/how-tos.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute-docs/content-types/how-tos.md b/contribute-docs/content-types/how-tos.md index c3cf1511c2..1f7afc16d1 100644 --- a/contribute-docs/content-types/how-tos.md +++ b/contribute-docs/content-types/how-tos.md @@ -4,7 +4,7 @@ navigation_title: "How-to guides" # How to write how-to guides -This page provides guidelines for writing effective how-to guides in Elastic documentation. To learn about other content types, refer to [](index.md). +This page provides guidelines for writing effective how-to guides in Elastic documentation. ## What is a how-to guide? From adf0a9e5c46a4bad28637dad3ff30d4c300ed789 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 9 Dec 2025 11:41:14 +0000 Subject: [PATCH 09/20] tweak for SEO, add frontmatter --- contribute-docs/content-types/how-tos.md | 3 ++- contribute-docs/content-types/index.md | 7 +++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/contribute-docs/content-types/how-tos.md b/contribute-docs/content-types/how-tos.md index 1f7afc16d1..3631affe41 100644 --- a/contribute-docs/content-types/how-tos.md +++ b/contribute-docs/content-types/how-tos.md @@ -1,10 +1,11 @@ --- navigation_title: "How-to guides" +description: "Guidelines for writing effective how-to guides in the Elastic documentation." --- # How to write how-to guides -This page provides guidelines for writing effective how-to guides in Elastic documentation. +This page provides guidelines for writing effective how-to guides in the Elastic docs. ## What is a how-to guide? diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md index a5e27f6817..4d7f6e93e5 100644 --- a/contribute-docs/content-types/index.md +++ b/contribute-docs/content-types/index.md @@ -1,5 +1,12 @@ +--- +navigation_title: "Content types" +description: "Overview of guidelines for choosing the appropriate content types in the Elastic documentation." +--- + # Elastic Docs content types +This page provides an overview of the different content types used in the Elastic documentation and guidelines for choosing the appropriate type for your docs page. + Content types ensure the Elastic Docs are structured, consistent, and easy for users to follow. When we use the right content type, we make it easy 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. From 38746f561c4c6d0cf09f69f05344bb90f181dc73 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 9 Dec 2025 11:42:01 +0000 Subject: [PATCH 10/20] words --- contribute-docs/content-types/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md index 4d7f6e93e5..aee021dc15 100644 --- a/contribute-docs/content-types/index.md +++ b/contribute-docs/content-types/index.md @@ -5,7 +5,7 @@ description: "Overview of guidelines for choosing the appropriate content types # Elastic Docs content types -This page provides an overview of the different content types used in the Elastic documentation and guidelines for choosing the appropriate type for your docs page. +This page provides an overview of the different content types used in the Elastic documentation and guidelines for choosing the appropriate type when creating new docs pages. Content types ensure the Elastic Docs are structured, consistent, and easy for users to follow. When we use the right content type, we make it easy for users to find the information they need and efficiently complete tasks. From 2d5194e5929d5c1d01f98da1a8698f40d5155989 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 9 Dec 2025 11:46:59 +0000 Subject: [PATCH 11/20] everybody loves success checkpoints --- contribute-docs/content-types/how-tos.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute-docs/content-types/how-tos.md b/contribute-docs/content-types/how-tos.md index 3631affe41..ed85168940 100644 --- a/contribute-docs/content-types/how-tos.md +++ b/contribute-docs/content-types/how-tos.md @@ -54,6 +54,7 @@ The following elements are required in how-to guides: :::{tip} Use the [stepper component](https://elastic.github.io/docs-builder/syntax/stepper/) for longer how-tos or those with complex steps. ::: +- **Success checkpoints:** Include confirmation steps that show users whether critical actions succeeded before moving on. ### Recommended sections @@ -68,7 +69,6 @@ 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. -- **Success checkpoints:** Include confirmation steps that show users whether critical actions succeeded before moving on. - **Error handling:** Mention common errors and how to resolve them. ## Template From 2f0129509398d151aaeeab5b32676b9b035e8611 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 9 Dec 2025 12:04:20 +0000 Subject: [PATCH 12/20] more nicer wordies --- contribute-docs/content-types/how-tos.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute-docs/content-types/how-tos.md b/contribute-docs/content-types/how-tos.md index ed85168940..e1f6d412dc 100644 --- a/contribute-docs/content-types/how-tos.md +++ b/contribute-docs/content-types/how-tos.md @@ -22,7 +22,7 @@ How-to guides focus on a single, self-contained task. For longer procedural cont ## Best practices -When you create how-to guides, use the following 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. From 21aa67a33f213f9a5f9450f6662bb0455d4aa874 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 9 Dec 2025 12:34:05 +0000 Subject: [PATCH 13/20] easier -> easy --- contribute-docs/content-types/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md index aee021dc15..90df381408 100644 --- a/contribute-docs/content-types/index.md +++ b/contribute-docs/content-types/index.md @@ -7,7 +7,7 @@ description: "Overview of guidelines for choosing the appropriate content types This page provides an overview of the different content types used in the Elastic documentation and guidelines for choosing the appropriate type when creating new docs pages. -Content types ensure the Elastic Docs are structured, consistent, and easy for users to follow. When we use the right content type, we make it easy for users to find the information they need and efficiently complete tasks. +Content types ensure the Elastic Docs are structured, consistent, and easy for users to follow. 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. @@ -49,4 +49,4 @@ A tutorial should always be a standalone page, meaning it should have only one c ## 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. \ No newline at end of file +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. From ba44ce9c7d1a4fdd8fa8314a9f98ff2291859e4b Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 9 Dec 2025 12:35:35 +0000 Subject: [PATCH 14/20] better verbiage Updated wording for clarity and completeness. --- contribute-docs/content-types/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md index 90df381408..a7ee2986bb 100644 --- a/contribute-docs/content-types/index.md +++ b/contribute-docs/content-types/index.md @@ -7,7 +7,7 @@ description: "Overview of guidelines for choosing the appropriate content types This page provides an overview of the different content types used in the Elastic documentation and guidelines for choosing the appropriate type when creating new docs pages. -Content types ensure the Elastic Docs are structured, consistent, and easy for users to follow. When we use the right content type, we make it easier for users to find the information they need and efficiently complete tasks. +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. From 15367ee563804bfdd03d4615cac442cdb44558b1 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 9 Dec 2025 14:45:49 +0000 Subject: [PATCH 15/20] Address Fabrizio's comments --- .../content-types/_snippets/templates/how-to-template.md | 7 ++++--- contribute-docs/content-types/how-tos.md | 9 ++++----- contribute-docs/content-types/index.md | 6 ++---- 3 files changed, 10 insertions(+), 12 deletions(-) diff --git a/contribute-docs/content-types/_snippets/templates/how-to-template.md b/contribute-docs/content-types/_snippets/templates/how-to-template.md index 1c2a1113fb..27a8f02579 100644 --- a/contribute-docs/content-types/_snippets/templates/how-to-template.md +++ b/contribute-docs/content-types/_snippets/templates/how-to-template.md @@ -1,5 +1,5 @@ --- -description: "A nice summary of the page fit for search results and tooltips." +description: "A concise summary of the page highlighting what the task accomplishes, fit for search results and tooltips." applies_to: stack: serverless: @@ -18,7 +18,7 @@ For complete guidance, refer to [the how-to guide](https://www.elastic.co/docs/c A precise description of the task using an action verb -Example: How to run Elasticsearch in Docker +Example: Run Elasticsearch in Docker -->