How-to guides

This page provides guidelines for writing effective how-to guides in the Elastic docs.

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.

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 to show both options.
  • If instructions differ per deployment type or version, use an 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.

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.

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:
  • applies_to: Tags for versioning/availability info per the cumulative docs guidelines
  • description: A brief summary of the page fit for search results and tooltips
  • product: The relevant Elastic product(s) used in the how-to

• A clear title: A precise description of the task using an action verb
  • For example, "Run Elasticsearch 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 for simple, linear steps. For longer how-tos or those with complex steps, use the stepper component.

• Success checkpoints: Include confirmation steps that show users whether critical actions succeeded before moving on.

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.

Consider including the following when they add value:

• Code annotations: Annotate important lines within code blocks.
• 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.

To get started writing your how-to guide, use the template.